@open-agent-toolkit/cli 0.0.10

package/dist/commands/project/archive/archive-utils.js

@@ -0,0 +1,236 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, posix as path } from 'node:path';
+import { promisify } from 'node:util';
+import { CliError } from '../../../errors/cli-error.js';
+import { copyDirectory, copySingleFile, dirExists, ensureDir, fileExists, } from '../../../fs/io.js';
+const execFileAsync = promisify(execFileCallback);
+export const ARCHIVE_SNAPSHOT_METADATA_FILENAME = '.oat-archive-source.json';
+function normalizeS3Uri(s3Uri) {
+    return s3Uri.trim().replace(/\/+$/, '');
+}
+function resolveRepoSlug(repoRoot) {
+    return basename(repoRoot).trim().replace(/\s+/g, '-');
+}
+function buildCompletionWarning(message) {
+    return {
+        ok: false,
+        warnings: [message],
+    };
+}
+function buildSyncError(message) {
+    return new CliError(message);
+}
+function requiresRemoteAccess(options) {
+    return Boolean(options.s3Uri &&
+        (options.mode === 'sync' || options.syncOnComplete === true));
+}
+export function buildRepoArchiveS3Uri(s3Uri, repoRoot) {
+    return `${normalizeS3Uri(s3Uri)}/${resolveRepoSlug(repoRoot)}/projects`;
+}
+export function buildProjectArchiveS3Uri(s3Uri, repoRoot, projectKey) {
+    return `${buildRepoArchiveS3Uri(s3Uri, repoRoot)}/${projectKey}`;
+}
+function normalizeArchiveDateStamp(timestamp) {
+    const isoPrefix = timestamp
+        .trim()
+        .match(/^(\d{4})-(\d{2})-(\d{2})/)
+        ?.slice(1);
+    if (isoPrefix) {
+        return isoPrefix.join('');
+    }
+    const digits = timestamp.replace(/\D/g, '');
+    if (digits.length >= 8) {
+        return digits.slice(0, 8);
+    }
+    return new Date().toISOString().slice(0, 10).replace(/-/g, '');
+}
+export function buildArchiveSnapshotName(projectName, timestamp) {
+    return `${normalizeArchiveDateStamp(timestamp)}-${projectName}`;
+}
+export function parseArchiveSnapshotName(snapshotName) {
+    const trimmedSnapshot = snapshotName.replace(/\/+$/, '');
+    const match = trimmedSnapshot.match(/^(\d{8})-(.+)$/);
+    if (!match) {
+        return {
+            projectName: trimmedSnapshot,
+            snapshotName: trimmedSnapshot,
+            dateStamp: null,
+        };
+    }
+    const dateStamp = match[1];
+    const projectName = match[2];
+    if (!dateStamp || !projectName) {
+        return {
+            projectName: trimmedSnapshot,
+            snapshotName: trimmedSnapshot,
+            dateStamp: null,
+        };
+    }
+    return {
+        projectName,
+        snapshotName: trimmedSnapshot,
+        dateStamp,
+    };
+}
+export function resolveLocalArchiveProjectPath(projectsRoot, projectName) {
+    const normalizedProjectsRoot = projectsRoot.replace(/\/+$/, '');
+    const projectsBase = path.dirname(normalizedProjectsRoot);
+    return path.join(projectsBase, 'archived', projectName);
+}
+function resolveCompletionArchivePath(archiveRepoRoot, projectsRoot, projectName) {
+    return join(archiveRepoRoot, resolveLocalArchiveProjectPath(projectsRoot, projectName));
+}
+function resolveGitPath(repoRoot, gitPath) {
+    const normalizedPath = gitPath.trim();
+    return isAbsolute(normalizedPath)
+        ? normalizedPath
+        : join(repoRoot, normalizedPath);
+}
+async function resolveArchiveRepoRoot(repoRoot, dependencies) {
+    const execFile = dependencies.gitExecFile ?? execFileAsync;
+    try {
+        const [{ stdout: commonDir }, { stdout: gitDir }] = await Promise.all([
+            execFile('git', ['rev-parse', '--git-common-dir'], {
+                cwd: repoRoot,
+                env: dependencies.env ?? process.env,
+            }),
+            execFile('git', ['rev-parse', '--git-dir'], {
+                cwd: repoRoot,
+                env: dependencies.env ?? process.env,
+            }),
+        ]);
+        const resolvedCommonDir = resolveGitPath(repoRoot, commonDir);
+        const resolvedGitDir = resolveGitPath(repoRoot, gitDir);
+        if (resolvedCommonDir === resolvedGitDir) {
+            return repoRoot;
+        }
+        const primaryRepoRoot = dirname(resolvedCommonDir);
+        const directoryExists = dependencies.dirExists ?? dirExists;
+        if (await directoryExists(primaryRepoRoot)) {
+            return primaryRepoRoot;
+        }
+    }
+    catch {
+        return repoRoot;
+    }
+    return repoRoot;
+}
+async function resolveUniqueArchivePath(archivePath, dependencies) {
+    const directoryExists = dependencies.dirExists ?? dirExists;
+    if (!(await directoryExists(archivePath))) {
+        return archivePath;
+    }
+    const timestamp = dependencies.timestamp?.() ?? new Date().toISOString();
+    const suffix = timestamp.replace(/[-:TZ.]/g, '').slice(0, 15);
+    return `${archivePath}-${suffix}`;
+}
+async function writeArchiveSnapshotMetadata(archivePath, metadata) {
+    await writeFile(join(archivePath, ARCHIVE_SNAPSHOT_METADATA_FILENAME), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+}
+async function exportProjectSummary(archivePath, snapshotName, summaryExportPath, repoRoot, dependencies) {
+    const summarySource = join(archivePath, 'summary.md');
+    const exists = dependencies.fileExists ?? fileExists;
+    if (!(await exists(summarySource))) {
+        return null;
+    }
+    const summaryTarget = join(repoRoot, summaryExportPath, `${snapshotName}.md`);
+    const copySummary = dependencies.copySingleFile ?? copySingleFile;
+    await copySummary(summarySource, summaryTarget);
+    return summaryTarget;
+}
+export async function archiveProjectOnCompletion(options, dependencies = {}) {
+    const makeDir = dependencies.ensureDir ?? ensureDir;
+    const copyProjectDirectory = dependencies.copyDirectory ?? copyDirectory;
+    const removePath = dependencies.removePath ??
+        (async (target, removeOptions) => rm(target, removeOptions));
+    const ensureAccess = dependencies.ensureS3ArchiveAccess ?? ensureS3ArchiveAccess;
+    const execFile = dependencies.execFile ?? execFileAsync;
+    const timestamp = dependencies.timestamp?.() ?? new Date().toISOString();
+    const snapshotName = buildArchiveSnapshotName(options.projectName, timestamp);
+    const archiveRepoRoot = await resolveArchiveRepoRoot(options.repoRoot, dependencies);
+    const archiveBasePath = resolveCompletionArchivePath(archiveRepoRoot, options.projectsRoot, options.projectName);
+    const archivePath = await resolveUniqueArchivePath(archiveBasePath, dependencies);
+    await makeDir(dirname(archivePath));
+    await copyProjectDirectory(options.projectPath, archivePath);
+    await writeArchiveSnapshotMetadata(archivePath, {
+        projectName: options.projectName,
+        snapshotName,
+    });
+    await removePath(options.projectPath, { recursive: true, force: true });
+    const warnings = [];
+    let summaryExportFile = null;
+    if (options.summaryExportPath) {
+        try {
+            summaryExportFile = await exportProjectSummary(archivePath, snapshotName, options.summaryExportPath, options.repoRoot, dependencies);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`Summary export to \`${options.summaryExportPath}\` failed: ${message}`);
+        }
+    }
+    let s3Path = null;
+    if (options.s3Uri && options.s3SyncOnComplete) {
+        const access = await ensureAccess({
+            mode: 'completion',
+            s3Uri: options.s3Uri,
+            syncOnComplete: options.s3SyncOnComplete,
+        }, {
+            execFile,
+            env: dependencies.env,
+        });
+        warnings.push(...access.warnings);
+        if (access.ok) {
+            s3Path = buildProjectArchiveS3Uri(options.s3Uri, options.repoRoot, snapshotName);
+            try {
+                await execFile('aws', ['s3', 'sync', archivePath, s3Path], {
+                    cwd: options.repoRoot,
+                    env: dependencies.env ?? process.env,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                warnings.push(`Archive S3 sync to \`${s3Path}\` failed: ${message}`);
+                s3Path = null;
+            }
+        }
+    }
+    return {
+        archivePath,
+        s3Path,
+        summaryExportFile,
+        warnings,
+    };
+}
+export async function ensureS3ArchiveAccess(options, dependencies = {}) {
+    if (!requiresRemoteAccess(options)) {
+        return { ok: true, warnings: [] };
+    }
+    const execFile = dependencies.execFile ?? execFileAsync;
+    const execOptions = { env: dependencies.env ?? process.env };
+    try {
+        await execFile('aws', ['--version'], execOptions);
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            if (options.mode === 'completion') {
+                return buildCompletionWarning('Archive S3 sync is enabled via `archive.s3SyncOnComplete`, but AWS CLI was not found on PATH. Skipping S3 archive sync.');
+            }
+            throw buildSyncError('AWS CLI is required for `oat project archive sync`, but it was not found on PATH. Install `aws` and retry.');
+        }
+        throw error;
+    }
+    try {
+        await execFile('aws', ['sts', 'get-caller-identity'], execOptions);
+        return { ok: true, warnings: [] };
+    }
+    catch {
+        if (options.mode === 'completion') {
+            return buildCompletionWarning('Archive S3 sync is enabled via `archive.s3SyncOnComplete` and `archive.s3Uri`, but AWS CLI is not configured for access. Skipping S3 archive sync.');
+        }
+        throw buildSyncError('AWS CLI is required for `oat project archive sync`, but it is not configured for access to `archive.s3Uri`. Configure AWS credentials or profile settings and retry.');
+    }
+}

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

@@ -0,0 +1,20 @@
+import { rm } from 'node:fs/promises';
+import { buildCommandContext, type CommandContext } from '../../../app/command-context.js';
+import { type OatConfig } from '../../../config/oat-config.js';
+import { Command } from 'commander';
+import { buildProjectArchiveS3Uri, buildRepoArchiveS3Uri, ensureS3ArchiveAccess, type ExecFileLike, resolveLocalArchiveProjectPath } from './archive-utils.js';
+export interface ProjectArchiveCommandDependencies {
+    buildCommandContext: (options: Parameters<typeof buildCommandContext>[0]) => CommandContext;
+    resolveProjectRoot: (cwd: string) => Promise<string>;
+    readOatConfig: (repoRoot: string) => Promise<OatConfig>;
+    resolveProjectsRoot: (repoRoot: string, env: NodeJS.ProcessEnv) => Promise<string>;
+    ensureS3ArchiveAccess: typeof ensureS3ArchiveAccess;
+    buildRepoArchiveS3Uri: typeof buildRepoArchiveS3Uri;
+    buildProjectArchiveS3Uri: typeof buildProjectArchiveS3Uri;
+    resolveLocalArchiveProjectPath: typeof resolveLocalArchiveProjectPath;
+    execFile: ExecFileLike;
+    removeDirectory: typeof rm;
+    processEnv: NodeJS.ProcessEnv;
+}
+export declare function createProjectArchiveCommand(overrides?: Partial<ProjectArchiveCommandDependencies>): Command;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAIhD,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,oBAAoB,CAAC;AAGnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAEL,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,YAAY,EAEjB,8BAA8B,EAC/B,MAAM,iBAAiB,CAAC;AASzB,MAAM,WAAW,iCAAiC;IAChD,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,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;IACpD,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;IACpD,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;IAC1D,8BAA8B,EAAE,OAAO,8BAA8B,CAAC;IACtE,QAAQ,EAAE,YAAY,CAAC;IACvB,eAAe,EAAE,OAAO,EAAE,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAoLD,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,iCAAiC,CAAM,GACzD,OAAO,CAuKT"}

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

@@ -0,0 +1,217 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { readFile, rm } from 'node:fs/promises';
+import { join, posix as path } from 'node:path';
+import { promisify } from 'node:util';
+import { buildCommandContext } from '../../../app/command-context.js';
+import { resolveProjectsRoot } from '../../shared/oat-paths.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { readOatConfig } from '../../../config/oat-config.js';
+import { CliError } from '../../../errors/cli-error.js';
+import { resolveProjectRoot } from '../../../fs/paths.js';
+import { Command } from 'commander';
+import { ARCHIVE_SNAPSHOT_METADATA_FILENAME, buildProjectArchiveS3Uri, buildRepoArchiveS3Uri, ensureS3ArchiveAccess, parseArchiveSnapshotName, resolveLocalArchiveProjectPath, } from './archive-utils.js';
+const execFileAsync = promisify(execFileCallback);
+function defaultDependencies() {
+    return {
+        buildCommandContext,
+        resolveProjectRoot,
+        readOatConfig,
+        resolveProjectsRoot,
+        ensureS3ArchiveAccess,
+        buildRepoArchiveS3Uri,
+        buildProjectArchiveS3Uri,
+        resolveLocalArchiveProjectPath,
+        execFile: execFileAsync,
+        removeDirectory: rm,
+        processEnv: process.env,
+    };
+}
+function resolveLocalArchiveRoot(projectsRoot) {
+    return path.join(path.dirname(projectsRoot.replace(/\/+$/, '')), 'archived');
+}
+function buildArchiveSyncArgs(source, target, options) {
+    const args = ['s3', 'sync', source, target];
+    if (options.dryRun) {
+        args.push('--dryrun');
+    }
+    return args;
+}
+async function runArchiveSync(repoRoot, source, target, options, dependencies) {
+    await dependencies.execFile('aws', buildArchiveSyncArgs(source, target, options), {
+        cwd: repoRoot,
+        env: dependencies.processEnv,
+    });
+}
+async function listArchiveSnapshots(repoRoot, projectsRoot, s3Uri, dependencies) {
+    const repoPrefix = `${dependencies.buildRepoArchiveS3Uri(s3Uri, repoRoot)}/`;
+    const { stdout } = await dependencies.execFile('aws', ['s3', 'ls', repoPrefix], {
+        cwd: repoRoot,
+        env: dependencies.processEnv,
+    });
+    return stdout
+        .split('\n')
+        .map((line) => line.match(/PRE\s+(.+?)\/?\s*$/)?.[1] ?? null)
+        .filter((snapshotName) => Boolean(snapshotName))
+        .map((snapshotName) => {
+        const parsed = parseArchiveSnapshotName(snapshotName);
+        return {
+            ...parsed,
+            source: dependencies.buildProjectArchiveS3Uri(s3Uri, repoRoot, snapshotName),
+            target: dependencies.resolveLocalArchiveProjectPath(projectsRoot, parsed.projectName),
+        };
+    });
+}
+function compareSnapshotEntries(left, right) {
+    if (left.dateStamp && right.dateStamp && left.dateStamp !== right.dateStamp) {
+        return left.dateStamp.localeCompare(right.dateStamp);
+    }
+    if (left.dateStamp && !right.dateStamp) {
+        return 1;
+    }
+    if (!left.dateStamp && right.dateStamp) {
+        return -1;
+    }
+    return left.snapshotName.localeCompare(right.snapshotName);
+}
+function selectLatestSnapshots(snapshots) {
+    const latestByProject = new Map();
+    for (const snapshot of snapshots) {
+        const current = latestByProject.get(snapshot.projectName);
+        if (!current || compareSnapshotEntries(snapshot, current) > 0) {
+            latestByProject.set(snapshot.projectName, snapshot);
+        }
+    }
+    return [...latestByProject.values()];
+}
+async function readLocalSnapshotName(repoRoot, target) {
+    try {
+        const content = await readFile(join(repoRoot, target, ARCHIVE_SNAPSHOT_METADATA_FILENAME), 'utf8');
+        const parsed = JSON.parse(content);
+        return typeof parsed.snapshotName === 'string' ? parsed.snapshotName : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function syncArchiveSnapshot(repoRoot, snapshot, options, dependencies) {
+    const currentSnapshotName = await readLocalSnapshotName(repoRoot, snapshot.target);
+    if (!options.force && currentSnapshotName === snapshot.snapshotName) {
+        return false;
+    }
+    if (!options.dryRun) {
+        await dependencies.removeDirectory(join(repoRoot, snapshot.target), {
+            recursive: true,
+            force: true,
+        });
+    }
+    await runArchiveSync(repoRoot, snapshot.source, snapshot.target, options, dependencies);
+    return true;
+}
+export function createProjectArchiveCommand(overrides = {}) {
+    const dependencies = {
+        ...defaultDependencies(),
+        ...overrides,
+    };
+    return new Command('archive')
+        .description('Manage archived project data')
+        .addCommand(new Command('sync')
+        .description('Sync archived project data from S3 into the local archive')
+        .argument('[project-name]', 'Archived project name to sync')
+        .option('--dry-run', 'Preview archive sync without downloading')
+        .option('--force', 'Replace the named local archive before syncing it from S3')
+        .action(async (projectName, options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        try {
+            if (options.force && !projectName) {
+                throw new CliError('`--force` requires a project name for `oat project archive sync`.');
+            }
+            const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+            const config = await dependencies.readOatConfig(repoRoot);
+            const s3Uri = config.archive?.s3Uri;
+            if (!s3Uri) {
+                throw new CliError('Archive sync requires `archive.s3Uri` to be configured. Set it with `oat config set archive.s3Uri <s3://...>` and retry.');
+            }
+            await dependencies.ensureS3ArchiveAccess({
+                mode: 'sync',
+                s3Uri,
+                syncOnComplete: config.archive?.s3SyncOnComplete ?? false,
+            });
+            const projectsRoot = await dependencies.resolveProjectsRoot(repoRoot, dependencies.processEnv);
+            const snapshots = await listArchiveSnapshots(repoRoot, projectsRoot, s3Uri, dependencies);
+            const targets = projectName
+                ? snapshots.filter((snapshot) => snapshot.projectName === projectName ||
+                    snapshot.snapshotName === projectName)
+                : selectLatestSnapshots(snapshots);
+            if (projectName && targets.length === 0) {
+                throw new CliError(`No archived snapshot found in S3 for project \`${projectName}\`.`);
+            }
+            const latestTarget = projectName
+                ? targets.reduce((latest, snapshot) => {
+                    if (!latest) {
+                        return snapshot;
+                    }
+                    return compareSnapshotEntries(snapshot, latest) > 0
+                        ? snapshot
+                        : latest;
+                }, null)
+                : null;
+            const snapshotsToSync = projectName
+                ? latestTarget
+                    ? [latestTarget]
+                    : []
+                : targets;
+            const appliedTargets = [];
+            const appliedSources = [];
+            for (const snapshot of snapshotsToSync) {
+                if (!snapshot) {
+                    continue;
+                }
+                const synced = await syncArchiveSnapshot(repoRoot, snapshot, options, dependencies);
+                if (synced) {
+                    appliedTargets.push(snapshot.target);
+                    appliedSources.push(snapshot.source);
+                }
+            }
+            const subject = projectName
+                ? `archived project \`${projectName}\``
+                : 'archived projects';
+            const targetSummary = appliedTargets.length > 0
+                ? appliedTargets.join(', ')
+                : resolveLocalArchiveRoot(projectsRoot);
+            const sourceSummary = appliedSources.length > 0
+                ? appliedSources.join(', ')
+                : dependencies.buildRepoArchiveS3Uri(s3Uri, repoRoot);
+            if (context.json) {
+                context.logger.json({
+                    status: 'ok',
+                    mode: options.dryRun ? 'dry-run' : 'apply',
+                    projectName: projectName ?? null,
+                    sources: appliedSources,
+                    targets: appliedTargets,
+                    skipped: appliedTargets.length === 0,
+                    force: options.force ?? false,
+                });
+            }
+            else if (options.dryRun) {
+                context.logger.info(`Dry-run: would sync ${subject} from ${sourceSummary} to ${targetSummary}.`);
+            }
+            else if (appliedTargets.length === 0) {
+                context.logger.info(`Skipped ${subject}; local archive is already using the latest remote snapshot.`);
+            }
+            else {
+                context.logger.info(`Synced ${subject} from ${sourceSummary} to ${targetSummary}.`);
+            }
+            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 : 1;
+        }
+    }));
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createProjectCommand(): Command;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/project/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,oBAAoB,IAAI,OAAO,CAQ9C"}

package/dist/commands/project/index.js

@@ -0,0 +1,15 @@
+import { Command } from 'commander';
+import { createProjectArchiveCommand } from './archive/index.js';
+import { createProjectNewCommand } from './new/index.js';
+import { createProjectOpenCommand } from './open/index.js';
+import { createProjectPauseCommand } from './pause/index.js';
+import { createProjectSetModeCommand } from './set-mode/index.js';
+export function createProjectCommand() {
+    return new Command('project')
+        .description('Manage OAT project workflows')
+        .addCommand(createProjectArchiveCommand())
+        .addCommand(createProjectNewCommand())
+        .addCommand(createProjectOpenCommand())
+        .addCommand(createProjectPauseCommand())
+        .addCommand(createProjectSetModeCommand());
+}

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

@@ -0,0 +1,17 @@
+import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
+import { Command } from 'commander';
+import { type ProjectScaffoldMode, type ScaffoldProjectResult } from './scaffold.js';
+interface ProjectNewDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+    scaffoldProject: (options: {
+        repoRoot: string;
+        projectName: string;
+        mode: ProjectScaffoldMode;
+        force: boolean;
+        setActive: boolean;
+        refreshDashboard: boolean;
+    }) => Promise<ScaffoldProjectResult>;
+}
+export declare function createProjectNewCommand(overrides?: Partial<ProjectNewDependencies>): Command;
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/new/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAE5C,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAC;AASpB,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,eAAe,EAAE,CAAC,OAAO,EAAE;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,mBAAmB,CAAC;QAC1B,KAAK,EAAE,OAAO,CAAC;QACf,SAAS,EAAE,OAAO,CAAC;QACnB,gBAAgB,EAAE,OAAO,CAAC;KAC3B,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACtC;AAiED,wBAAgB,uBAAuB,CACrC,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CAiCT"}

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

@@ -0,0 +1,76 @@
+import { buildCommandContext, } from '../../../app/command-context.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { Command, Option } from 'commander';
+import { scaffoldProject as defaultScaffoldProject, } from './scaffold.js';
+const DEFAULT_DEPENDENCIES = {
+    buildCommandContext,
+    scaffoldProject: defaultScaffoldProject,
+};
+function reportSuccess(context, projectName, result) {
+    if (context.json) {
+        context.logger.json({
+            status: 'ok',
+            projectName,
+            mode: result.mode,
+            projectPath: result.projectPath,
+            projectsRoot: result.projectsRoot,
+            createdFiles: result.createdFiles,
+            skippedFiles: result.skippedFiles,
+            activePointerUpdated: result.activePointerUpdated,
+            dashboardRefreshed: result.dashboardRefreshed,
+        });
+        return;
+    }
+    context.logger.info(`Created/updated OAT project: ${projectName}`);
+    context.logger.info(`Project path: ${result.projectPath}`);
+    if (result.activePointerUpdated) {
+        context.logger.info('Active project updated in local config: .oat/config.local.json');
+    }
+}
+async function runProjectNew(projectName, options, context, dependencies) {
+    try {
+        const result = await dependencies.scaffoldProject({
+            repoRoot: context.cwd,
+            projectName,
+            mode: options.mode,
+            force: options.force,
+            setActive: options.setActive,
+            refreshDashboard: options.dashboard,
+        });
+        reportSuccess(context, projectName, result);
+        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 = 1;
+    }
+}
+export function createProjectNewCommand(overrides = {}) {
+    const dependencies = {
+        ...DEFAULT_DEPENDENCIES,
+        ...overrides,
+    };
+    return new Command('new')
+        .description('Create or update an OAT project scaffold')
+        .argument('<name>', 'Project name (letters, numbers, dash, underscore)')
+        .addOption(new Option('--mode <mode>', 'Scaffold mode')
+        .choices(['spec-driven', 'quick', 'import'])
+        .default('spec-driven'))
+        .option('--force', 'Non-destructive scaffold; create missing files only')
+        .option('--no-set-active', 'Do not update active project in local config')
+        .option('--no-dashboard', 'Do not refresh .oat/state.md after scaffold')
+        .action(async (name, options, command) => {
+        if (name.startsWith('-')) {
+            command.help();
+            return;
+        }
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runProjectNew(name, options, context, dependencies);
+    });
+}

package/dist/commands/project/new/scaffold.d.ts

@@ -0,0 +1,24 @@
+export type ProjectScaffoldMode = 'spec-driven' | 'quick' | 'import';
+export interface ScaffoldProjectOptions {
+    repoRoot: string;
+    projectName: string;
+    mode?: ProjectScaffoldMode;
+    force?: boolean;
+    setActive?: boolean;
+    refreshDashboard?: boolean;
+    env?: NodeJS.ProcessEnv;
+    today?: string;
+    nowUtc?: string;
+    refreshDashboardCallback?: (repoRoot: string) => void | Promise<void>;
+}
+export interface ScaffoldProjectResult {
+    mode: ProjectScaffoldMode;
+    projectsRoot: string;
+    projectPath: string;
+    createdFiles: string[];
+    skippedFiles: string[];
+    activePointerUpdated: boolean;
+    dashboardRefreshed: boolean;
+}
+export declare function scaffoldProject(options: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/commands/project/new/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/new/scaffold.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wBAAwB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAqMD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAqDhC"}