@brimveyn/aimux 1.20.4 → 1.22.0

package/src/cli/client/project-resolver.ts

@@ -0,0 +1,112 @@
+import type { ProjectRecord, WorkspaceRecord } from '../../state/types'
+
+import { findMostRecentProject, loadProjectCatalog } from '../../state/project-catalog'
+
+/**
+ * Where a command's target project came from. An orchestrator needs this to
+ * tell "I asked for pragma-once" from "aimux guessed, and the UI had moved on":
+ * `active` is the only origin that can silently follow the UI to another repo.
+ */
+export type ProjectOrigin = 'flag' | 'env' | 'active'
+
+export interface ResolvedProject {
+  origin: ProjectOrigin
+  record: ProjectRecord
+}
+
+/** Env pin for headless orchestrators — `--project` still wins over it. */
+export const PROJECT_ENV_VAR = 'AIMUX_PROJECT'
+/** ponytail: pre-rename spelling, honoured for one release. Drop with --workspace. */
+const LEGACY_PROJECT_ENV_VAR = 'AIMUX_WORKSPACE'
+
+/** The project's primary (root) workspace, i.e. the repository it is about. */
+export function findPrimaryWorkspace(project: ProjectRecord): WorkspaceRecord | undefined {
+  return project.workspaces?.find((workspace) => workspace.source === 'primary')
+}
+
+/**
+ * The repo every fresh workspace for this project is cut from. Surfaced in
+ * every worker envelope so an agent can see *which project* it just acted on
+ * instead of inferring it from a workspace path hash.
+ */
+export function projectRepoRoot(project: ProjectRecord): string | null {
+  return findPrimaryWorkspace(project)?.repoRoot ?? project.projectPath ?? null
+}
+
+/** Stable project identity block embedded in command output. */
+export function projectIdentity(project: ProjectRecord): {
+  id: string
+  name: string
+  repoRoot: string | null
+} {
+  return { id: project.id, name: project.name, repoRoot: projectRepoRoot(project) }
+}
+
+/**
+ * Resolve `--project W` to a project record from the catalog, reporting where
+ * the choice came from. Precedence: the explicit flag, then `AIMUX_PROJECT`,
+ * then the most recently opened project. Throws when the catalog is empty (no
+ * project has ever been created) or when the explicit name/id doesn't match.
+ *
+ * Matching: exact id wins; otherwise exact name (case-sensitive); otherwise
+ * unique case-insensitive name match.
+ */
+export function resolveProjectWithOrigin(name: string | undefined): ResolvedProject {
+  const projects = loadProjectCatalog()
+  if (projects.length === 0) {
+    throw new Error(
+      'no projects found — create one from the aimux UI first (or pass --project once created)'
+    )
+  }
+
+  const flag = name !== undefined && name !== '' ? name : undefined
+  const env = process.env[PROJECT_ENV_VAR] ?? process.env[LEGACY_PROJECT_ENV_VAR]
+  const fromEnv = env != null && env !== '' ? env : undefined
+  const selector = flag ?? fromEnv
+  if (selector === undefined) {
+    const active = findMostRecentProject(projects)
+    if (!active) {
+      throw new Error('no active project and the catalog is empty')
+    }
+    return { origin: 'active', record: active }
+  }
+
+  return {
+    origin: flag !== undefined ? 'flag' : 'env',
+    record: matchProject(projects, selector),
+  }
+}
+
+export function resolveProject(name: string | undefined): ProjectRecord {
+  return resolveProjectWithOrigin(name).record
+}
+
+function matchProject(projects: ProjectRecord[], name: string): ProjectRecord {
+  const byId = projects.find((project) => project.id === name)
+  if (byId) return byId
+
+  const exactNameMatches = projects.filter((project) => project.name === name)
+  if (exactNameMatches.length > 1) {
+    throw new Error(
+      `project "${name}" matches multiple projects: ${exactNameMatches.map((s) => s.id).join(', ')}`
+    )
+  }
+  const exactOnly = exactNameMatches[0]
+  if (exactOnly) return exactOnly
+
+  const lower = name.toLowerCase()
+  const ciMatches = projects.filter((project) => project.name.toLowerCase() === lower)
+  if (ciMatches.length > 1) {
+    throw new Error(
+      `project "${name}" matches multiple projects: ${ciMatches.map((s) => s.id).join(', ')}`
+    )
+  }
+  const ciOnly = ciMatches[0]
+  if (ciOnly) return ciOnly
+
+  throw new Error(`project not found: ${name}`)
+}
+
+export function listProjects(): ProjectRecord[] {
+  return loadProjectCatalog()
+}

package/src/cli/commands/project/close.ts

@@ -0,0 +1,32 @@
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_PROJECT_LIFECYCLE } from '../../../ipc/protocol'
+import { resolveProject } from '../../client/project-resolver'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const projectClose: CliCommand = {
+  args: [{ complete: { kind: 'dynamic', source: 'project' }, name: 'project', required: true }],
+  flags: SHARED_FLAGS,
+  group: 'project',
+  run: async (ctx) => {
+    const target = ctx.args.positionals[0]
+    if (typeof target !== 'string' || target.length === 0) {
+      throw new Error('target project is required (id or name)')
+    }
+    const project = resolveProject(target)
+
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_PROJECT_LIFECYCLE)) {
+      throw new Error(
+        'daemon predates projectLifecycle capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    await daemon.expectOk('closeProject', { targetProjectId: project.id })
+    writeJson({ closedProjectId: project.id, name: project.name })
+    return EXIT_OK
+  },
+  summary: 'Close a project (via the UI when attached, otherwise the catalog)',
+  verb: 'close',
+}

package/src/cli/commands/project/create.ts

@@ -0,0 +1,93 @@
+import { resolve as resolvePath } from 'node:path'
+
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_PROJECT_LIFECYCLE } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, EXIT_TIMEOUT, writeJson } from '../../output'
+
+const DEFAULT_WAIT_TIMEOUT_MS = 30_000
+
+export const projectCreate: CliCommand = {
+  args: [{ complete: { kind: 'none' }, name: 'name', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      complete: { kind: 'file' },
+      description: 'project path to associate with the project',
+      kind: 'string',
+      name: 'project',
+    },
+    {
+      description: 'immediately switch the running UI to the new project',
+      kind: 'boolean',
+      name: 'switch',
+    },
+    {
+      description: 'with --switch, wait until the UI confirms the switch completed',
+      kind: 'boolean',
+      name: 'wait',
+    },
+    {
+      description: 'timeout for --wait, in milliseconds (default 30000)',
+      kind: 'number',
+      name: 'timeout',
+    },
+  ],
+  group: 'project',
+  run: async (ctx) => {
+    const name = ctx.args.positionals[0]
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error('project name is required')
+    }
+    const projectRaw =
+      typeof ctx.args.flags.project === 'string' ? ctx.args.flags.project : undefined
+    const projectPath = projectRaw === undefined ? undefined : resolvePath(projectRaw)
+    const doSwitch = ctx.args.flags.switch === true
+    const wait = ctx.args.flags.wait === true
+    const timeoutMs =
+      typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_WAIT_TIMEOUT_MS
+
+    if (wait && !doSwitch) {
+      // Without --switch, the UI never emits an ack event, so there's
+      // nothing meaningful for --wait to wait on.
+      throw new Error('--wait requires --switch (nothing to wait for otherwise)')
+    }
+
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_PROJECT_LIFECYCLE)) {
+      throw new Error(
+        'daemon predates projectLifecycle capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    if (!wait) {
+      await daemon.expectOk('createProject', { name, projectPath, switch: doSwitch })
+      writeJson({ name, projectPath, switch: doSwitch })
+      return EXIT_OK
+    }
+
+    // Subscribe BEFORE sending the request. The UI's create+switch path
+    // relays as `projectSwitched` once handleCreateProjectEffect has
+    // dispatched load-project. Match on name+projectPath since the CLI
+    // doesn't know the id the UI will assign to the new project.
+    const settled = new Promise<number>((resolve) => {
+      const off = daemon.on('projectSwitched', (payload) => {
+        off()
+        clearTimeout(timer)
+        writeJson({ name, projectId: payload.projectId, projectPath, switch: doSwitch })
+        resolve(EXIT_OK)
+      })
+      const timer = setTimeout(() => {
+        off()
+        writeJson({ error: 'timed out waiting for projectSwitched', name, projectPath })
+        resolve(EXIT_TIMEOUT)
+      }, timeoutMs)
+    })
+
+    await daemon.expectOk('createProject', { name, projectPath, switch: doSwitch })
+    return settled
+  },
+  summary: 'Create a new project (via the UI when attached, otherwise the catalog)',
+  verb: 'create',
+}

package/src/cli/commands/project/list.ts

@@ -0,0 +1,25 @@
+import type { CliCommand } from '../../registry'
+
+import { listProjects } from '../../client/project-resolver'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const projectList: CliCommand = {
+  args: [],
+  flags: SHARED_FLAGS,
+  group: 'project',
+  run: async () => {
+    const projects = listProjects()
+    writeJson({
+      projects: projects.map((project) => ({
+        id: project.id,
+        lastOpenedAt: project.lastOpenedAt,
+        name: project.name,
+        projectPath: project.projectPath,
+      })),
+    })
+    return EXIT_OK
+  },
+  summary: 'List known projects in the profile catalog',
+  verb: 'list',
+}

package/src/cli/commands/project/show.ts

@@ -0,0 +1,32 @@
+import type { CliCommand } from '../../registry'
+
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const projectShow: CliCommand = {
+  args: [],
+  flags: SHARED_FLAGS,
+  group: 'project',
+  run: async (ctx) => {
+    const project = ctx.getProject()
+    writeJson({
+      activeWorkspaceId: project.activeWorkspaceId,
+      createdAt: project.createdAt,
+      id: project.id,
+      lastOpenedAt: project.lastOpenedAt,
+      name: project.name,
+      projectPath: project.projectPath,
+      workspaces:
+        project.workspaces?.map((w) => ({
+          branch: w.branch,
+          id: w.id,
+          name: w.name,
+          path: w.path,
+          source: w.source,
+        })) ?? [],
+    })
+    return EXIT_OK
+  },
+  summary: 'Show the active project (or the one named via --project)',
+  verb: 'show',
+}

package/src/cli/commands/{workspace → project}/switch.ts

@@ -1,14 +1,14 @@
 import type { CliCommand } from '../../registry'
 
-import { IPC_CAPABILITY_WORKSPACE_LIFECYCLE } from '../../../ipc/protocol'
-import { resolveWorkspace } from '../../client/workspace-resolver'
+import { IPC_CAPABILITY_PROJECT_LIFECYCLE } from '../../../ipc/protocol'
+import { resolveProject } from '../../client/project-resolver'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, EXIT_TIMEOUT, writeJson } from '../../output'
 
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000
 
-export const workspaceSwitch: CliCommand = {
-  args: [{ complete: { kind: 'dynamic', source: 'workspace' }, name: 'workspace', required: true }],
+export const projectSwitch: CliCommand = {
+  args: [{ complete: { kind: 'dynamic', source: 'project' }, name: 'project', required: true }],
   flags: [
     ...SHARED_FLAGS,
     {
@@ -22,54 +22,54 @@ export const workspaceSwitch: CliCommand = {
       name: 'timeout',
     },
   ],
-  group: 'workspace',
+  group: 'project',
   run: async (ctx) => {
     const target = ctx.args.positionals[0]
     if (typeof target !== 'string' || target.length === 0) {
-      throw new Error('target workspace is required (id or name)')
+      throw new Error('target project is required (id or name)')
     }
-    const session = resolveWorkspace(target)
+    const project = resolveProject(target)
     const wait = ctx.args.flags.wait === true
     const timeoutMs =
       typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_WAIT_TIMEOUT_MS
 
     const daemon = await ctx.getDaemon()
-    if (!daemon.hasCapability(IPC_CAPABILITY_WORKSPACE_LIFECYCLE)) {
+    if (!daemon.hasCapability(IPC_CAPABILITY_PROJECT_LIFECYCLE)) {
       throw new Error(
-        'daemon predates workspaceLifecycle capability — restart aimux to pick up the new daemon'
+        'daemon predates projectLifecycle capability — restart aimux to pick up the new daemon'
       )
     }
 
     if (!wait) {
-      await daemon.expectOk('switchWorkspace', { targetSessionId: session.id })
-      writeJson({ name: session.name, targetSessionId: session.id })
+      await daemon.expectOk('switchProject', { targetProjectId: project.id })
+      writeJson({ name: project.name, targetProjectId: project.id })
       return EXIT_OK
     }
 
     // Subscribe BEFORE sending the request so we don't miss the broadcast for
-    // the no-UI path (the daemon emits `workspaceSwitched` synchronously in
+    // the no-UI path (the daemon emits `projectSwitched` synchronously in
     // that branch).
     const settled = new Promise<number>((resolve) => {
-      const off = daemon.on('workspaceSwitched', (payload) => {
-        if (payload.sessionId !== session.id) return
+      const off = daemon.on('projectSwitched', (payload) => {
+        if (payload.projectId !== project.id) return
         off()
         clearTimeout(timer)
-        writeJson({ name: session.name, targetSessionId: session.id })
+        writeJson({ name: project.name, targetProjectId: project.id })
         resolve(EXIT_OK)
       })
       const timer = setTimeout(() => {
         off()
         writeJson({
-          error: 'timed out waiting for workspaceSwitched',
-          targetSessionId: session.id,
+          error: 'timed out waiting for projectSwitched',
+          targetProjectId: project.id,
         })
         resolve(EXIT_TIMEOUT)
       }, timeoutMs)
     })
 
-    await daemon.expectOk('switchWorkspace', { targetSessionId: session.id })
+    await daemon.expectOk('switchProject', { targetProjectId: project.id })
     return settled
   },
-  summary: 'Switch the UI (or catalog when headless) to another workspace',
+  summary: 'Switch the UI (or catalog when headless) to another project',
   verb: 'switch',
 }

package/src/cli/commands/tab/await.ts

@@ -45,7 +45,7 @@ export const tabAwait: CliCommand = {
     const timeoutMs =
       typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_TIMEOUT_MS
 
-    const workspace = ctx.getWorkspace()
+    const project = ctx.getProject()
     const daemon = await ctx.getDaemon()
     if (
       !daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH) ||
@@ -57,7 +57,7 @@ export const tabAwait: CliCommand = {
       )
     }
 
-    const attach = await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+    const attach = await daemon.attach({ cols: 0, projectId: project.id, rows: 0, thin: true })
     const tab = attach.tabs.find((t) => t.id === tabId)
     if (!tab) {
       // Exit 3 (runtime) via runCli — NOT 4, which is reserved for

package/src/cli/commands/tab/close.ts

@@ -14,7 +14,7 @@ export const tabClose: CliCommand = {
       throw new Error('tabId is required')
     }
 
-    const workspace = ctx.getWorkspace()
+    const project = ctx.getProject()
     const daemon = await ctx.getDaemon()
 
     if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
@@ -22,12 +22,12 @@ export const tabClose: CliCommand = {
         'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
       )
     }
-    await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+    await daemon.attach({ cols: 0, projectId: project.id, rows: 0, thin: true })
     await daemon.expectOk('closeTab', { tabId })
 
     writeJson({ ok: true })
     return EXIT_OK
   },
-  summary: 'Close a tab in the workspace',
+  summary: 'Close a tab in the project',
   verb: 'close',
 }