@open-agent-toolkit/cli 0.2.41 → 0.2.46

package/dist/commands/project/open/index.js

@@ -1,12 +1,18 @@
 import { readFile as defaultReadFile, writeFile as defaultWriteFile, } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { buildCommandContext } from '../../../app/command-context.js';
+import { defaultGitRunner } from '../../project/sync/git.js';
+import { readSyncedRecord } from '../../project/sync/record.js';
+import { commitRecordChange as defaultCommitRecordChange, pullSynced as defaultPullSynced, pushSynced as defaultPushSynced, } from '../../project/sync/ref-sync.js';
+import { resolveSyncedTarget, } from '../../project/sync/resolve-target.js';
 import { getFrontmatterBlock, getFrontmatterField, } from '../../shared/frontmatter.js';
 import { removeFrontmatterField, replaceFrontmatter, upsertFrontmatterField, } from '../../shared/frontmatter-write.js';
 import { resolveProjectsRoot } from '../../shared/oat-paths.js';
+import { PROJECT_SCOPES, resolveProjectScope, resolveScopeRoot, syncedRecordPath, } from '../../shared/project-scope.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { generateStateDashboard as defaultGenerateStateDashboard, } from '../../state/generate.js';
 import { readOatLocalConfig, setActiveProject, writeOatLocalConfig, } from '../../../config/oat-config.js';
+import { CliError } from '../../../errors/cli-error.js';
 import { dirExists, fileExists } from '../../../fs/io.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
 import { assertValidProjectStateFilesystemContent } from '../../../validation/project-state.js';
@@ -23,14 +29,133 @@ const DEFAULT_DEPENDENCIES = {
     writeFile: defaultWriteFile,
     dirExists,
     fileExists,
+    readSyncedRecord,
+    resolveSyncedTarget,
+    pullSynced: defaultPullSynced,
+    pushSynced: defaultPushSynced,
+    commitRecordChange: defaultCommitRecordChange,
+    gitRunner: defaultGitRunner,
     processEnv: process.env,
     now: () => new Date(),
 };
+function pointerPath(repoRoot, absolutePath) {
+    const relativePath = relative(repoRoot, absolutePath);
+    return relativePath === '..' ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)
+        ? absolutePath
+        : relativePath.split(sep).join('/');
+}
+function successfulPull(result) {
+    return (result.status === 'created' ||
+        result.status === 'updated' ||
+        result.status === 'up-to-date');
+}
+async function materializeSyncedProject(repoRoot, target, dependencies) {
+    const result = await dependencies.pullSynced(target, dependencies.gitRunner, {
+        adopt: target.adopt,
+        adoptionRecord: target.adoptionRecord,
+    });
+    if (!successfulPull(result)) {
+        throw new CliError(`Unable to open synced project ${target.slug}: pull ${result.status}.`, 1);
+    }
+    if (result.pendingRecordPaths?.length) {
+        await dependencies.commitRecordChange(repoRoot, result.pendingRecordPaths, `chore(oat): adopt synced project ${target.slug}`, dependencies.gitRunner, { projectRoots: target });
+    }
+}
+async function resolveProject(repoRoot, projectsRoot, input, dependencies) {
+    const sharedRoot = resolveScopeRoot(repoRoot, projectsRoot, 'shared');
+    const explicit = isAbsolute(input) || input.includes('/');
+    if (explicit) {
+        const fullProjectPath = isAbsolute(input)
+            ? resolve(input)
+            : resolve(repoRoot, input);
+        const scope = resolveProjectScope(fullProjectPath, sharedRoot, repoRoot);
+        if (!scope) {
+            throw new CliError(`Project path is outside configured scope roots: ${input}`, 1);
+        }
+        const projectName = basename(fullProjectPath);
+        let syncTarget;
+        if (scope === 'synced') {
+            syncTarget = await dependencies.resolveSyncedTarget({ repoRoot, env: dependencies.processEnv }, fullProjectPath, {}, { allowMissingCheckout: true });
+            if (!(await dependencies.dirExists(fullProjectPath)) ||
+                syncTarget.adopt) {
+                await materializeSyncedProject(repoRoot, syncTarget, dependencies);
+            }
+        }
+        else if (!(await dependencies.dirExists(fullProjectPath))) {
+            throw new CliError(`Project not found: ${input}`, 1);
+        }
+        return {
+            projectName,
+            projectPath: pointerPath(repoRoot, fullProjectPath),
+            fullProjectPath,
+            scope,
+            syncTarget,
+        };
+    }
+    const candidates = [];
+    for (const scope of PROJECT_SCOPES) {
+        const scopeRoot = resolveScopeRoot(repoRoot, projectsRoot, scope);
+        const fullProjectPath = join(scopeRoot, input);
+        if (await dependencies.dirExists(fullProjectPath)) {
+            candidates.push({ scope, fullProjectPath, present: true });
+        }
+        else if (scope === 'synced' &&
+            (await dependencies.readSyncedRecord(syncedRecordPath(scopeRoot, input))) !== null) {
+            candidates.push({ scope, fullProjectPath, present: false });
+        }
+    }
+    if (candidates.length > 1) {
+        throw new CliError(`Project name "${input}" is ambiguous across scopes: ${candidates
+            .map((candidate) => candidate.scope)
+            .join(', ')}. Pass an explicit project path.`, 1);
+    }
+    let candidate = candidates[0];
+    let syncTarget;
+    if (!candidate) {
+        try {
+            syncTarget = await dependencies.resolveSyncedTarget({ repoRoot, env: dependencies.processEnv }, input, {}, { allowMissingCheckout: true });
+            candidate = {
+                scope: 'synced',
+                fullProjectPath: syncTarget.projectPath,
+                present: false,
+            };
+        }
+        catch (error) {
+            if (error instanceof CliError && error.exitCode === 1) {
+                throw new CliError(`Project not found: ${input}`, 1);
+            }
+            throw error;
+        }
+    }
+    if (candidate.scope === 'synced') {
+        syncTarget ??= await dependencies.resolveSyncedTarget({ repoRoot, env: dependencies.processEnv }, candidate.fullProjectPath, {}, { allowMissingCheckout: true });
+        if (!candidate.present || syncTarget.adopt) {
+            await materializeSyncedProject(repoRoot, syncTarget, dependencies);
+        }
+    }
+    return {
+        projectName: input,
+        projectPath: pointerPath(repoRoot, candidate.fullProjectPath),
+        fullProjectPath: candidate.fullProjectPath,
+        scope: candidate.scope,
+        syncTarget,
+    };
+}
+async function publishSyncedTransition(target, action, dependencies) {
+    const result = await dependencies.pushSynced(target, dependencies.gitRunner, {
+        message: `chore(oat): ${action} synced project ${target.slug}`,
+    });
+    if (result.status !== 'pushed' && result.status !== 'up-to-date') {
+        throw new CliError(`Unable to ${action} synced project ${target.slug}: push ${result.status}; active project pointer was not changed.`, 1);
+    }
+}
 async function maybeResumePausedProject(statePath, projectPath, dependencies) {
     const stateContent = await dependencies.readFile(statePath, 'utf8');
     const frontmatter = getFrontmatterBlock(stateContent);
     if (!frontmatter) {
-        throw new Error(`state.md is missing frontmatter: ${statePath}`);
+        throw new CliError(`state.md is missing frontmatter: ${statePath}`, 1);
     }
     if (getFrontmatterField(frontmatter, 'oat_lifecycle') !== 'paused') {
         return false;
@@ -41,10 +166,15 @@ async function maybeResumePausedProject(statePath, projectPath, dependencies) {
     nextBlock = upsertFrontmatterField(nextBlock, 'oat_project_state_updated', dependencies.now().toISOString(), true).nextBlock;
     if (nextBlock !== frontmatter) {
         const nextContent = replaceFrontmatter(stateContent, nextBlock);
-        await assertValidProjectStateFilesystemContent(nextContent, {
-            filePath: statePath,
-            projectPath,
-        });
+        try {
+            await assertValidProjectStateFilesystemContent(nextContent, {
+                filePath: statePath,
+                projectPath,
+            });
+        }
+        catch (error) {
+            throw new CliError(error instanceof Error ? error.message : String(error), 1);
+        }
         await dependencies.writeFile(statePath, nextContent, 'utf8');
     }
     return true;
@@ -53,23 +183,25 @@ async function runProjectOpen(projectName, options, context, dependencies) {
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const projectsRoot = await dependencies.resolveProjectsRoot(repoRoot, dependencies.processEnv);
-        const projectPath = join(projectsRoot, projectName);
-        const fullProjectPath = join(repoRoot, projectPath);
-        if (!(await dependencies.dirExists(fullProjectPath))) {
-            throw new Error(`Project not found: ${projectName}`);
-        }
+        const resolved = await resolveProject(repoRoot, projectsRoot, projectName, dependencies);
+        const { projectPath, fullProjectPath } = resolved;
         const statePath = join(fullProjectPath, 'state.md');
         if (!(await dependencies.fileExists(statePath))) {
-            throw new Error(`Project state.md not found: ${statePath}`);
+            throw new CliError(`Project state.md not found: ${statePath}`, 1);
         }
         const localConfig = await dependencies.readOatLocalConfig(repoRoot);
         const previousActiveProject = localConfig.activeProject ?? null;
-        if (previousActiveProject === projectPath) {
+        const resumedFromPaused = await maybeResumePausedProject(statePath, fullProjectPath, dependencies);
+        if (resumedFromPaused && resolved.syncTarget) {
+            await publishSyncedTransition(resolved.syncTarget, 'resume', dependencies);
+        }
+        if (previousActiveProject === projectPath && !resumedFromPaused) {
             if (context.json) {
                 context.logger.json({
                     status: 'ok',
-                    projectName,
+                    projectName: resolved.projectName,
                     projectPath,
+                    scope: resolved.scope,
                     previousActiveProject,
                     resumedFromPaused: false,
                     reason: options.reason ?? null,
@@ -82,7 +214,6 @@ async function runProjectOpen(projectName, options, context, dependencies) {
             process.exitCode = 0;
             return;
         }
-        const resumedFromPaused = await maybeResumePausedProject(statePath, fullProjectPath, dependencies);
         await dependencies.setActiveProject(repoRoot, projectPath);
         if (localConfig.lastPausedProject === projectPath) {
             const updatedConfig = await dependencies.readOatLocalConfig(repoRoot);
@@ -95,8 +226,9 @@ async function runProjectOpen(projectName, options, context, dependencies) {
         if (context.json) {
             context.logger.json({
                 status: 'ok',
-                projectName,
+                projectName: resolved.projectName,
                 projectPath,
+                scope: resolved.scope,
                 previousActiveProject,
                 resumedFromPaused,
                 reason: options.reason ?? null,
@@ -104,10 +236,10 @@ async function runProjectOpen(projectName, options, context, dependencies) {
         }
         else {
             if (previousActiveProject) {
-                context.logger.info(`Switching from ${basename(previousActiveProject)} to ${projectName}.`);
+                context.logger.info(`Switching from ${basename(previousActiveProject)} to ${resolved.projectName}.`);
             }
             else {
-                context.logger.info(`Opened project: ${projectName}`);
+                context.logger.info(`Opened project: ${resolved.projectName}`);
             }
             if (resumedFromPaused) {
                 context.logger.info('Resumed paused project and cleared pause metadata.');
@@ -126,7 +258,7 @@ async function runProjectOpen(projectName, options, context, dependencies) {
         else {
             context.logger.error(message);
         }
-        process.exitCode = 1;
+        process.exitCode = error instanceof CliError ? error.exitCode : 2;
     }
 }
 export function createProjectOpenCommand(overrides = {}) {

package/dist/commands/project/pause/index.d.ts

@@ -1,5 +1,8 @@
 import { readFile as defaultReadFile, writeFile as defaultWriteFile } from 'node:fs/promises';
 import { buildCommandContext, type CommandContext } from '../../../app/command-context.js';
+import { type GitRunner } from '../../project/sync/git.js';
+import { type PushResult, type SyncTarget } from '../../project/sync/ref-sync.js';
+import { resolveSyncedTarget } from '../../project/sync/resolve-target.js';
 import { type GenerateStateResult } from '../../state/generate.js';
 import { type OatLocalConfig } from '../../../config/oat-config.js';
 import { dirExists, fileExists } from '../../../fs/io.js';
@@ -19,6 +22,11 @@ interface ProjectPauseDependencies {
     writeFile: typeof defaultWriteFile;
     dirExists: typeof dirExists;
     fileExists: typeof fileExists;
+    resolveSyncedTarget: typeof resolveSyncedTarget;
+    pushSynced: (target: SyncTarget, git: GitRunner, options: {
+        message?: string;
+    }) => Promise<PushResult>;
+    gitRunner: GitRunner;
     processEnv: NodeJS.ProcessEnv;
     now: () => Date;
 }

package/dist/commands/project/pause/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/pause/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,IAAI,eAAe,EAC3B,SAAS,IAAI,gBAAgB,EAC9B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAShF,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,KAC9B,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,sBAAsB,EAAE,CAAC,OAAO,EAAE;QAChC,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACnC,QAAQ,EAAE,OAAO,eAAe,CAAC;IACjC,SAAS,EAAE,OAAO,gBAAgB,CAAC;IACnC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AA0ID,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CAsBT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/pause/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,IAAI,eAAe,EAC3B,SAAS,IAAI,gBAAgB,EAC9B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,UAAU,EAChB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,mBAAmB,EAEpB,MAAM,uCAAuC,CAAC;AAe/C,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAC/C,cAAc,CAAC;IACpB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,KAC9B,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,sBAAsB,EAAE,CAAC,OAAO,EAAE;QAChC,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACnC,QAAQ,EAAE,OAAO,eAAe,CAAC;IACjC,SAAS,EAAE,OAAO,gBAAgB,CAAC;IACnC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,UAAU,EAAE,CACV,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAC1B,OAAO,CAAC,UAAU,CAAC,CAAC;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAwTD,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CAsBT"}

package/dist/commands/project/pause/index.js

@@ -1,12 +1,17 @@
 import { readFile as defaultReadFile, writeFile as defaultWriteFile, } from 'node:fs/promises';
-import { join } from 'node:path';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { buildCommandContext } from '../../../app/command-context.js';
+import { defaultGitRunner } from '../../project/sync/git.js';
+import { pushSynced as defaultPushSynced, } from '../../project/sync/ref-sync.js';
+import { resolveSyncedTarget, } from '../../project/sync/resolve-target.js';
 import { getFrontmatterBlock } from '../../shared/frontmatter.js';
 import { removeFrontmatterField, replaceFrontmatter, upsertFrontmatterField, } from '../../shared/frontmatter-write.js';
 import { resolveProjectsRoot } from '../../shared/oat-paths.js';
+import { PROJECT_SCOPES, resolveProjectScope, resolveScopeRoot, } from '../../shared/project-scope.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { generateStateDashboard as defaultGenerateStateDashboard, } from '../../state/generate.js';
 import { clearActiveProject, readOatLocalConfig, } from '../../../config/oat-config.js';
+import { CliError } from '../../../errors/cli-error.js';
 import { dirExists, fileExists } from '../../../fs/io.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
 import { assertValidProjectStateFilesystemContent } from '../../../validation/project-state.js';
@@ -22,40 +27,118 @@ const DEFAULT_DEPENDENCIES = {
     writeFile: defaultWriteFile,
     dirExists,
     fileExists,
+    resolveSyncedTarget,
+    pushSynced: defaultPushSynced,
+    gitRunner: defaultGitRunner,
     processEnv: process.env,
     now: () => new Date(),
 };
+function pointerPath(repoRoot, absolutePath) {
+    const relativePath = relative(repoRoot, absolutePath);
+    return relativePath === '..' ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)
+        ? absolutePath
+        : relativePath.split(sep).join('/');
+}
+async function resolveNamedProject(repoRoot, projectsRoot, input, dependencies) {
+    const sharedRoot = resolveScopeRoot(repoRoot, projectsRoot, 'shared');
+    const explicit = isAbsolute(input) || input.includes('/');
+    if (explicit) {
+        const fullProjectPath = isAbsolute(input)
+            ? resolve(input)
+            : resolve(repoRoot, input);
+        const scope = resolveProjectScope(fullProjectPath, sharedRoot, repoRoot);
+        if (!scope) {
+            throw new CliError(`Project path is outside configured scope roots: ${input}`, 1);
+        }
+        if (!(await dependencies.dirExists(fullProjectPath))) {
+            throw new CliError(`Project not found: ${input}`, 1);
+        }
+        return {
+            projectName: basename(fullProjectPath),
+            projectPath: pointerPath(repoRoot, fullProjectPath),
+            fullProjectPath,
+            scope,
+            syncTarget: scope === 'synced'
+                ? await dependencies.resolveSyncedTarget({ repoRoot, env: dependencies.processEnv }, fullProjectPath)
+                : undefined,
+        };
+    }
+    const candidates = [];
+    for (const scope of PROJECT_SCOPES) {
+        const fullProjectPath = join(resolveScopeRoot(repoRoot, projectsRoot, scope), input);
+        if (!(await dependencies.dirExists(fullProjectPath)))
+            continue;
+        candidates.push({
+            projectName: input,
+            projectPath: pointerPath(repoRoot, fullProjectPath),
+            fullProjectPath,
+            scope,
+            syncTarget: scope === 'synced'
+                ? await dependencies.resolveSyncedTarget({ repoRoot, env: dependencies.processEnv }, fullProjectPath)
+                : undefined,
+        });
+    }
+    if (candidates.length > 1) {
+        throw new CliError(`Project name "${input}" is ambiguous across scopes: ${candidates
+            .map((candidate) => candidate.scope)
+            .join(', ')}. Pass an explicit project path.`, 1);
+    }
+    if (!candidates[0]) {
+        throw new CliError(`Project not found: ${input}`, 1);
+    }
+    return candidates[0];
+}
+async function publishPausedState(target, dependencies) {
+    const result = await dependencies.pushSynced(target, dependencies.gitRunner, {
+        message: `chore(oat): pause synced project ${target.slug}`,
+    });
+    if (result.status !== 'pushed' && result.status !== 'up-to-date') {
+        const recovery = result.status === 'conflict'
+            ? ` Resolve the conflicted files without discarding either side, then run oat project pull ${target.slug} --continue followed by oat project push ${target.slug}, then re-run oat project pause ${target.slug} to finish and clear the active pointer; or run oat project pull ${target.slug} --abort to leave the committed local pause unpublished.`
+            : ` The committed local pause was retained with a clean checkout; re-run oat project pause ${target.slug} to retry publication.`;
+        throw new PausePublicationError(`Unable to pause synced project ${target.slug}: push ${result.status}; active project pointer was not changed.${recovery}`, result.status);
+    }
+    return result;
+}
+class PausePublicationError extends CliError {
+    status;
+    constructor(message, status) {
+        super(message, 1);
+        this.status = status;
+    }
+}
 async function runProjectPause(projectName, options, context, dependencies) {
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const projectsRoot = await dependencies.resolveProjectsRoot(repoRoot, dependencies.processEnv);
         const localConfig = await dependencies.readOatLocalConfig(repoRoot);
         const activeProject = localConfig.activeProject ?? null;
-        let projectPath;
-        let resolvedProjectName;
+        let resolved;
         if (projectName) {
-            projectPath = join(projectsRoot, projectName);
-            resolvedProjectName = projectName;
+            resolved = await resolveNamedProject(repoRoot, projectsRoot, projectName, dependencies);
         }
         else {
             if (!activeProject) {
-                throw new Error('No project specified and no active project');
+                throw new CliError('No project specified and no active project', 1);
             }
-            projectPath = activeProject;
-            resolvedProjectName = projectPath.split('/').at(-1) ?? projectPath;
-        }
-        const fullProjectPath = join(repoRoot, projectPath);
-        if (!(await dependencies.dirExists(fullProjectPath))) {
-            throw new Error(`Project not found: ${resolvedProjectName}`);
+            resolved = await resolveNamedProject(repoRoot, projectsRoot, activeProject, dependencies);
         }
+        const { projectName: resolvedProjectName, projectPath, fullProjectPath, } = resolved;
         const statePath = join(fullProjectPath, 'state.md');
         if (!(await dependencies.fileExists(statePath))) {
-            throw new Error(`Project state.md not found: ${statePath}`);
+            throw new CliError(`Project state.md not found: ${statePath}`, 1);
         }
         const content = await dependencies.readFile(statePath, 'utf8');
+        const prePauseHead = resolved.syncTarget
+            ? (await dependencies.gitRunner.run(['rev-parse', 'HEAD'], {
+                cwd: resolved.syncTarget.projectPath,
+            })).stdout
+            : null;
         const frontmatter = getFrontmatterBlock(content);
         if (!frontmatter) {
-            throw new Error(`state.md is missing frontmatter: ${statePath}`);
+            throw new CliError(`state.md is missing frontmatter: ${statePath}`, 1);
         }
         let nextBlock = upsertFrontmatterField(frontmatter, 'oat_lifecycle', 'paused', true).nextBlock;
         const nowIso = dependencies.now().toISOString();
@@ -69,12 +152,38 @@ async function runProjectPause(projectName, options, context, dependencies) {
         }
         if (nextBlock !== frontmatter) {
             const nextContent = replaceFrontmatter(content, nextBlock);
-            await assertValidProjectStateFilesystemContent(nextContent, {
-                filePath: statePath,
-                projectPath: fullProjectPath,
-            });
+            try {
+                await assertValidProjectStateFilesystemContent(nextContent, {
+                    filePath: statePath,
+                    projectPath: fullProjectPath,
+                });
+            }
+            catch (error) {
+                throw new CliError(error instanceof Error ? error.message : String(error), 1);
+            }
             await dependencies.writeFile(statePath, nextContent, 'utf8');
         }
+        if (resolved.syncTarget) {
+            try {
+                await publishPausedState(resolved.syncTarget, dependencies);
+            }
+            catch (error) {
+                if (nextBlock !== frontmatter &&
+                    !(error instanceof PausePublicationError)) {
+                    const pauseCommitRetained = resolved.syncTarget && prePauseHead
+                        ? (await dependencies.gitRunner.run(['rev-parse', 'HEAD'], {
+                            cwd: resolved.syncTarget.projectPath,
+                        })).stdout !== prePauseHead
+                        : false;
+                    if (pauseCommitRetained && resolved.syncTarget) {
+                        const detail = error instanceof Error ? error.message : String(error);
+                        throw new PausePublicationError(`Unable to pause synced project ${resolved.syncTarget.slug}: publication failed: ${detail}. Active project pointer was not changed. The committed local pause was retained with a clean checkout; re-run oat project pause ${resolved.syncTarget.slug} to retry publication.`, 'failed');
+                    }
+                    await dependencies.writeFile(statePath, content, 'utf8');
+                }
+                throw error;
+            }
+        }
         const pointerCleared = activeProject === projectPath;
         if (pointerCleared) {
             await dependencies.clearActiveProject(repoRoot, {
@@ -87,6 +196,7 @@ async function runProjectPause(projectName, options, context, dependencies) {
                 status: 'ok',
                 projectName: resolvedProjectName,
                 projectPath,
+                scope: resolved.scope,
                 pointerCleared,
                 reason: options.reason ?? null,
             });
@@ -107,7 +217,7 @@ async function runProjectPause(projectName, options, context, dependencies) {
         else {
             context.logger.error(message);
         }
-        process.exitCode = 1;
+        process.exitCode = error instanceof CliError ? error.exitCode : 2;
     }
 }
 export function createProjectPauseCommand(overrides = {}) {

package/dist/commands/project/prune/index.d.ts

@@ -0,0 +1,21 @@
+import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
+import { type GitRunner } from '../../project/sync/git.js';
+import { type PruneResult, type SyncTarget } from '../../project/sync/ref-sync.js';
+import { resolveSyncedTarget } from '../../project/sync/resolve-target.js';
+import { Command } from 'commander';
+interface ProjectPruneDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+    resolveProjectRoot: (cwd: string) => Promise<string>;
+    resolveSyncedTarget: typeof resolveSyncedTarget;
+    pruneSynced: (target: SyncTarget, git: GitRunner, options: {
+        force: boolean;
+        commit: boolean;
+    }) => Promise<PruneResult>;
+    readProjectState: (target: SyncTarget, git: GitRunner) => Promise<string | null>;
+    gitRunner: GitRunner;
+    processEnv: NodeJS.ProcessEnv;
+}
+export declare function readPruneProjectState(target: SyncTarget, git: GitRunner): Promise<string | null>;
+export declare function createProjectPruneCommand(overrides?: Partial<ProjectPruneDependencies>): Command;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/project/prune/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/prune/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE9E,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAS5E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,UAAU,wBAAwB;IAChC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,WAAW,EAAE,CACX,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,KACzC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1B,gBAAgB,EAAE,CAChB,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,SAAS,KACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA+BxB;AAmED,wBAAgB,yBAAyB,CACvC,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,OAAO,CAmBT"}

package/dist/commands/project/prune/index.js

@@ -0,0 +1,95 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildCommandContext, } from '../../../app/command-context.js';
+import { defaultGitRunner } from '../../project/sync/git.js';
+import { readSyncedRecord } from '../../project/sync/record.js';
+import { pruneSynced, } from '../../project/sync/ref-sync.js';
+import { resolveSyncedTarget } from '../../project/sync/resolve-target.js';
+import { getFrontmatterBlock, parseFrontmatterScalarFields, } from '../../shared/frontmatter.js';
+import { syncedRecordPath } from '../../shared/project-scope.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { CliError } from '../../../errors/cli-error.js';
+import { resolveProjectRoot } from '../../../fs/paths.js';
+import { Command } from 'commander';
+export async function readPruneProjectState(target, git) {
+    try {
+        return await readFile(join(target.projectPath, 'state.md'), 'utf8');
+    }
+    catch {
+        // A completed or not-yet-pulled project may have no checkout.
+    }
+    const fetched = await git.run(['fetch', target.remote, `+${target.ref}:${target.ref}`], { cwd: target.repoRoot, allowFailure: true });
+    if (fetched.code === 0) {
+        const shown = await git.run(['show', `${target.ref}:state.md`], {
+            cwd: target.repoRoot,
+            allowFailure: true,
+        });
+        if (shown.code === 0)
+            return shown.stdout;
+    }
+    const record = await readSyncedRecord(syncedRecordPath(target.syncedRoot, target.slug));
+    const snapshot = record?.archiveSnapshot ?? target.slug;
+    try {
+        return await readFile(join(target.syncedRoot, '..', 'archived', snapshot, 'state.md'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+const DEFAULT_DEPENDENCIES = {
+    buildCommandContext,
+    resolveProjectRoot,
+    resolveSyncedTarget,
+    pruneSynced,
+    readProjectState: readPruneProjectState,
+    gitRunner: defaultGitRunner,
+    processEnv: process.env,
+};
+function hasOpenPr(state) {
+    const frontmatter = state ? getFrontmatterBlock(state) : null;
+    if (!frontmatter)
+        return false;
+    const parsed = parseFrontmatterScalarFields(frontmatter, ['oat_pr_status']);
+    return parsed.valid && parsed.values.oat_pr_status === 'open';
+}
+async function runPrune(context, pathOrSlug, options, dependencies) {
+    try {
+        const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+        const target = await dependencies.resolveSyncedTarget({ repoRoot, env: dependencies.processEnv }, pathOrSlug, { gitRunner: dependencies.gitRunner }, {
+            allowMissingCheckout: true,
+            allowStagedPruneDeletion: true,
+        });
+        const state = await dependencies.readProjectState(target, dependencies.gitRunner);
+        if (!options.force && hasOpenPr(state)) {
+            throw new CliError(`Refusing to prune ${target.slug} while its PR is open. Pass --force to confirm; pinned links will stop resolving.`, 1);
+        }
+        context.logger.warn(`Pruning ${target.slug} removes ${target.ref}; pinned links will stop resolving.`);
+        const result = await dependencies.pruneSynced(target, dependencies.gitRunner, { force: options.force, commit: options.commit });
+        const payload = { ...result, ref: target.ref };
+        if (context.json)
+            context.logger.json(payload);
+        else
+            context.logger.info(`Pruned synced project ${target.slug}.`);
+        process.exitCode = 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (context.json)
+            context.logger.json({ status: 'error', message });
+        else
+            context.logger.error(message);
+        process.exitCode = error instanceof CliError ? error.exitCode : 2;
+    }
+}
+export function createProjectPruneCommand(overrides = {}) {
+    const dependencies = { ...DEFAULT_DEPENDENCIES, ...overrides };
+    return new Command('prune')
+        .description('Permanently remove a synced project and its ref')
+        .argument('[project-path|slug]', 'Synced project path or slug')
+        .option('--force', 'Prune despite open PR or unsafe checkout state', false)
+        .option('--no-commit', 'Do not commit the discovery record deletion')
+        .action(async (pathOrSlug, options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runPrune(context, pathOrSlug, options, dependencies);
+    });
+}

package/dist/commands/project/pull/index.d.ts

@@ -0,0 +1,28 @@
+import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
+import { type GitRunner } from '../../project/sync/git.js';
+import { commitRecordChange as defaultCommitRecordChange, type PullChildResult, type PullResult, type AdoptionRecordState, type SyncTarget } from '../../project/sync/ref-sync.js';
+import { resolveSyncedTarget } from '../../project/sync/resolve-target.js';
+import { Command } from 'commander';
+interface ProjectPullDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+    resolveProjectRoot: (cwd: string) => Promise<string>;
+    resolveSyncedTarget: typeof resolveSyncedTarget;
+    pullSynced: (target: SyncTarget, git: GitRunner, options?: {
+        adopt?: boolean;
+        adoptionRecord?: AdoptionRecordState;
+        now?: Date;
+    }) => Promise<PullResult>;
+    pullChildren: (target: SyncTarget, git: GitRunner) => Promise<PullChildResult[]>;
+    commitRecordChange: typeof defaultCommitRecordChange;
+    continueSynced: (target: SyncTarget, git: GitRunner, options?: {
+        adopt?: boolean;
+        adoptionRecord?: AdoptionRecordState;
+        now?: Date;
+    }) => Promise<PullResult>;
+    abortSynced: (target: SyncTarget, git: GitRunner) => Promise<void>;
+    gitRunner: GitRunner;
+    processEnv: NodeJS.ProcessEnv;
+}
+export declare function createProjectPullCommand(overrides?: Partial<ProjectPullDependencies>): Command;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/project/pull/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/pull/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAEL,kBAAkB,IAAI,yBAAyB,EAI/C,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAChB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,mBAAmB,EAEpB,MAAM,uCAAuC,CAAC;AAI/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,UAAU,EAAE,CACV,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,cAAc,CAAC,EAAE,mBAAmB,CAAC;QACrC,GAAG,CAAC,EAAE,IAAI,CAAC;KACZ,KACE,OAAO,CAAC,UAAU,CAAC,CAAC;IACzB,YAAY,EAAE,CACZ,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,SAAS,KACX,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAChC,kBAAkB,EAAE,OAAO,yBAAyB,CAAC;IACrD,cAAc,EAAE,CACd,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,SAAS,EACd,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,cAAc,CAAC,EAAE,mBAAmB,CAAC;QACrC,GAAG,CAAC,EAAE,IAAI,CAAC;KACZ,KACE,OAAO,CAAC,UAAU,CAAC,CAAC;IACzB,WAAW,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAiLD,wBAAgB,wBAAwB,CACtC,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAqBT"}