feat: link once — git-style walk-up resolution for .insta/project.json (#23)

readProject resolves the nearest ancestor link, so every command works
from any subdirectory of a linked project; writeProject targets the found
root (branch switch in src/ no longer mints a nested link). Fresh links
in unlinked trees still bind cwd.


Claude-Session: https://claude.ai/code/session_01GMbAe5K1RfwaAcge5inX7P

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: tonychang04

src/config.ts

@@ -1,6 +1,6 @@
 // CLI config: global (~/.insta/config.json: api url + tokens) and per-project (./.insta/project.json).
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 
 const GLOBAL_DIR = join(homedir(), '.insta')
@@ -37,15 +37,35 @@ export async function writeGlobal(c: GlobalConfig): Promise<void> {
   await writeFile(GLOBAL_FILE, JSON.stringify(c, null, 2))
 }
 
+/** Git-style ancestor lookup: the nearest directory at-or-above `cwd` containing
+ *  .insta/project.json — so "link once" works from any subdirectory of the project. */
+export async function findProjectRoot(cwd = process.cwd()): Promise<string | null> {
+  let dir = resolve(cwd)
+  for (;;) {
+    try {
+      await readFile(join(dir, PROJECT_DIR, PROJECT_FILE), 'utf8')
+      return dir
+    } catch { /* keep climbing */ }
+    const parent = dirname(dir)
+    if (parent === dir) return null // filesystem root
+    dir = parent
+  }
+}
+
 export async function readProject(cwd = process.cwd()): Promise<ProjectConfig | null> {
+  const root = await findProjectRoot(cwd)
+  if (!root) return null
   try {
-    return JSON.parse(await readFile(join(cwd, PROJECT_DIR, PROJECT_FILE), 'utf8')) as ProjectConfig
+    return JSON.parse(await readFile(join(root, PROJECT_DIR, PROJECT_FILE), 'utf8')) as ProjectConfig
   } catch {
     return null
   }
 }
 
+/** Writes to the existing project root when inside a linked project (branch switches from a
+ *  subdirectory must not mint a nested link); a fresh `link` in an unlinked tree writes to cwd. */
 export async function writeProject(c: ProjectConfig, cwd = process.cwd()): Promise<void> {
-  await mkdir(join(cwd, PROJECT_DIR), { recursive: true })
-  await writeFile(join(cwd, PROJECT_DIR, PROJECT_FILE), JSON.stringify(c, null, 2))
+  const target = (await findProjectRoot(cwd)) ?? cwd
+  await mkdir(join(target, PROJECT_DIR), { recursive: true })
+  await writeFile(join(target, PROJECT_DIR, PROJECT_FILE), JSON.stringify(c, null, 2))
 }

test/project-link.test.ts

@@ -0,0 +1,36 @@
+// "Link once and it works" requires git-style ancestor lookup: commands run from any
+// subdirectory of a linked project must resolve the SAME link, and updates (branch switch)
+// must rewrite the link at the project root — never mint a nested .insta in the subdir.
+import { test, expect } from 'vitest'
+import { mkdtempSync, mkdirSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { readProject, writeProject } from '../src/config.js'
+
+const proj = { projectId: 'p-1', orgId: 'o-1', branch: 'main' }
+
+function linkedProjectWithSubdir(): { root: string; sub: string } {
+  const root = mkdtempSync(join(tmpdir(), 'insta-link-'))
+  const sub = join(root, 'src', 'deep')
+  mkdirSync(sub, { recursive: true })
+  return { root, sub }
+}
+
+test('readProject finds the link from a nested subdirectory', async () => {
+  const { root, sub } = linkedProjectWithSubdir()
+  await writeProject(proj, root)
+  expect(await readProject(sub)).toMatchObject({ projectId: 'p-1' })
+})
+
+test('writeProject from a subdirectory updates the root link, not a nested copy', async () => {
+  const { root, sub } = linkedProjectWithSubdir()
+  await writeProject(proj, root)
+  await writeProject({ ...proj, branch: 'feat' }, sub) // e.g. `insta branch switch feat` run in src/deep
+  expect((await readProject(root))?.branch).toBe('feat')
+  expect(existsSync(join(sub, '.insta'))).toBe(false) // no second link minted
+})
+
+test('unlinked directories still resolve to null (walk stops at fs root)', async () => {
+  const lone = mkdtempSync(join(tmpdir(), 'insta-unlinked-'))
+  expect(await readProject(lone)).toBeNull()
+})