@open-agent-toolkit/cli 0.2.5 → 0.2.7

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

@@ -1,5 +1,6 @@
 import { execFile as execFileCallback } from 'node:child_process';
-import { rm, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, readFile, realpath, rename, rm, writeFile, } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, posix as path, relative, resolve, sep, } from 'node:path';
 import { promisify } from 'node:util';
 import { CliError } from '../../../errors/cli-error.js';
@@ -280,6 +281,304 @@ async function exportProjectSummary(archivePath, snapshotName, summaryExportPath
     await copySummary(summarySource, summaryTarget);
     return summaryTarget;
 }
+function parseProjectRecapManifest(contents) {
+    let value;
+    try {
+        value = JSON.parse(contents);
+    }
+    catch {
+        throw new CliError('Selected project recap has an invalid manifest.json.');
+    }
+    if (!isProjectRecapManifestV1(value)) {
+        throw new CliError('Selected project recap manifest does not match the explainer-kit manifest contract.');
+    }
+    const expectedImmutablePaths = new Set([
+        value.source.factBasePath,
+        'source/fact-base.md',
+        value.theme.path,
+        ...value.artifacts.flatMap((artifact) => [
+            artifact.contentPath,
+            ...(artifact.status === 'built' &&
+                typeof artifact.renderedPath === 'string'
+                ? [artifact.renderedPath]
+                : []),
+        ]),
+    ]);
+    const recordedImmutablePaths = Object.keys(value.immutableHashes);
+    if (expectedImmutablePaths.size === 0 ||
+        expectedImmutablePaths.size !== recordedImmutablePaths.length ||
+        [...expectedImmutablePaths].some((relativePath) => !(relativePath in value.immutableHashes)) ||
+        value.source.factBaseHash !==
+            value.immutableHashes[value.source.factBasePath] ||
+        value.theme.hash !== value.immutableHashes[value.theme.path] ||
+        value.artifacts.some((artifact) => artifact.status === 'built' &&
+            typeof artifact.renderedPath === 'string' &&
+            artifact.hash !== value.immutableHashes[artifact.renderedPath])) {
+        throw new CliError('Selected project recap manifest immutable hashes do not cover the complete v1 package.');
+    }
+    return value;
+}
+function isProjectRecapManifestV1(value) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, [
+            'schemaVersion',
+            'runId',
+            'slug',
+            'recipe',
+            'createdAt',
+            'source',
+            'theme',
+            'artifacts',
+            'immutableHashes',
+            'outcome',
+            'buildRecord',
+            'warnings',
+        ], ['publishReceipt']) ||
+        value.schemaVersion !== 'explainer-kit.manifest/v1' ||
+        !isNonEmptyString(value.runId) ||
+        typeof value.slug !== 'string' ||
+        !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value.slug) ||
+        !isDateTime(value.createdAt) ||
+        !isRecord(value.recipe) ||
+        !hasExactKeys(value.recipe, ['id', 'version']) ||
+        !isNonEmptyString(value.recipe.id) ||
+        !isNonEmptyString(value.recipe.version) ||
+        !isRecord(value.source) ||
+        !hasExactKeys(value.source, ['factBasePath', 'factBaseHash', 'inputHashes'], ['sourceRevision']) ||
+        !isSafeRelativePath(value.source.factBasePath) ||
+        !isSha256(value.source.factBaseHash) ||
+        !isHashMap(value.source.inputHashes) ||
+        (value.source.sourceRevision !== undefined &&
+            !isNonEmptyString(value.source.sourceRevision)) ||
+        !isRecord(value.theme) ||
+        !hasExactKeys(value.theme, ['path', 'hash', 'derived']) ||
+        value.theme.path !== 'theme.resolved.json' ||
+        !isSha256(value.theme.hash) ||
+        typeof value.theme.derived !== 'boolean' ||
+        !Array.isArray(value.artifacts) ||
+        !value.artifacts.every(isManifestArtifact) ||
+        new Set(value.artifacts.map((artifact) => JSON.stringify(artifact)))
+            .size !== value.artifacts.length ||
+        !isHashMap(value.immutableHashes) ||
+        !['built-durable', 'built-not-durable', 'failed', 'incomplete'].includes(String(value.outcome)) ||
+        !isPathHashRecord(value.buildRecord, 'build-record.json') ||
+        (value.publishReceipt !== undefined &&
+            !isPathHashRecord(value.publishReceipt, 'publish-receipt.json')) ||
+        !Array.isArray(value.warnings) ||
+        !value.warnings.every(isNonEmptyString)) {
+        return false;
+    }
+    return true;
+}
+function isManifestArtifact(value) {
+    if (!isRecord(value) ||
+        !hasExactKeys(value, ['id', 'type', 'contentPath', 'status', 'rebuildable'], [
+            'renderedPath',
+            'mediaType',
+            'hash',
+            'rebuild',
+            'durableEvidence',
+            'failure',
+        ]) ||
+        !isNonEmptyString(value.id) ||
+        !['hub', 'diagram', 'explainer', 'deck', 'catalog'].includes(String(value.type)) ||
+        !isSafeRelativePath(value.contentPath) ||
+        !['built', 'failed', 'skipped'].includes(String(value.status)) ||
+        typeof value.rebuildable !== 'boolean' ||
+        (value.renderedPath !== undefined &&
+            (!isSafeRelativePath(value.renderedPath) ||
+                !value.renderedPath.startsWith('site/'))) ||
+        (value.mediaType !== undefined && !isNonEmptyString(value.mediaType)) ||
+        (value.hash !== undefined && !isSha256(value.hash)) ||
+        (value.status === 'built' && !isSha256(value.hash)) ||
+        (value.rebuildable === true && !isRebuildRecord(value.rebuild)) ||
+        (value.rebuild !== undefined && !isRebuildRecord(value.rebuild)) ||
+        (value.durableEvidence !== undefined &&
+            (!Array.isArray(value.durableEvidence) ||
+                !value.durableEvidence.every(isDurableEvidence))) ||
+        (value.failure !== undefined && !isFailureRecord(value.failure))) {
+        return false;
+    }
+    return true;
+}
+function isRebuildRecord(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ['argv', 'cwd', 'inputHashes']) &&
+        Array.isArray(value.argv) &&
+        value.argv.length > 0 &&
+        value.argv.every((argument) => typeof argument === 'string') &&
+        isNonEmptyString(value.cwd) &&
+        isHashMap(value.inputHashes));
+}
+function isDurableEvidence(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ['kind', 'ref', 'paths', 'attestedAt'], ['supersedes']) &&
+        ['commit', 'publish'].includes(String(value.kind)) &&
+        isNonEmptyString(value.ref) &&
+        isUniqueSafePathArray(value.paths) &&
+        isDateTime(value.attestedAt) &&
+        (value.supersedes === undefined ||
+            (isRecord(value.supersedes) &&
+                hasExactKeys(value.supersedes, ['ref', 'paths']) &&
+                isNonEmptyString(value.supersedes.ref) &&
+                isUniqueSafePathArray(value.supersedes.paths))));
+}
+function isFailureRecord(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ['code', 'message', 'recovery']) &&
+        isNonEmptyString(value.code) &&
+        isNonEmptyString(value.message) &&
+        Array.isArray(value.recovery) &&
+        value.recovery.length > 0 &&
+        value.recovery.every(isNonEmptyString));
+}
+function isPathHashRecord(value, expectedPath) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ['path', 'hash']) &&
+        value.path === expectedPath &&
+        isSha256(value.hash));
+}
+function isHashMap(value) {
+    return (isRecord(value) &&
+        Object.entries(value).every(([relativePath, hash]) => isSafeRelativePath(relativePath) && isSha256(hash)));
+}
+function isUniqueSafePathArray(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every(isSafeRelativePath) &&
+        new Set(value).size === value.length);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    return (required.every((key) => key in value) &&
+        Object.keys(value).every((key) => allowed.has(key)));
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isDateTime(value) {
+    return (typeof value === 'string' &&
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) &&
+        !Number.isNaN(Date.parse(value)));
+}
+function isSafeRelativePath(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        !isAbsolute(value) &&
+        !value.includes('\\') &&
+        value.split('/').every((segment) => segment !== '' && segment !== '..'));
+}
+function isSha256(value) {
+    return typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+}
+async function pathExists(target) {
+    try {
+        await lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+function assertInsideExplainers(explainersRoot, selectedRunRoot) {
+    if (selectedRunRoot === explainersRoot ||
+        !isInsidePath(explainersRoot, selectedRunRoot)) {
+        throw new CliError('Selected project recap run must be inside the project `explainers/` directory.');
+    }
+}
+async function resolveSelectedProjectRecapRun(projectPath, projectRecapRun) {
+    const explainersRoot = resolve(projectPath, 'explainers');
+    const selectedRunRoot = resolve(projectPath, projectRecapRun);
+    assertInsideExplainers(explainersRoot, selectedRunRoot);
+    const [realExplainersRoot, realSelectedRunRoot] = await Promise.all([
+        realpath(explainersRoot),
+        realpath(selectedRunRoot),
+    ]);
+    assertInsideExplainers(realExplainersRoot, realSelectedRunRoot);
+    return selectedRunRoot;
+}
+function parseExpectedSha256(value, relativePath) {
+    const match = value.match(/^sha256:([a-f0-9]{64})$/);
+    if (!match?.[1]) {
+        throw new CliError(`Selected project recap manifest has an invalid hash for \`${relativePath}\`.`);
+    }
+    return match[1];
+}
+async function verifyProjectRecapImmutableHashes(stagedRoot, manifest) {
+    const entries = Object.entries(manifest.immutableHashes);
+    const realStagedRoot = await realpath(stagedRoot);
+    for (const [relativePath, expectedHash] of entries) {
+        const artifactPath = resolve(stagedRoot, relativePath);
+        if (artifactPath === stagedRoot ||
+            !isInsidePath(stagedRoot, artifactPath)) {
+            throw new CliError(`Selected project recap manifest path \`${relativePath}\` escapes the recap package.`);
+        }
+        const realArtifactPath = await realpath(artifactPath);
+        if (!isInsidePath(realStagedRoot, realArtifactPath)) {
+            throw new CliError(`Selected project recap manifest path \`${relativePath}\` escapes the recap package.`);
+        }
+        const actualHash = createHash('sha256')
+            .update(await readFile(realArtifactPath))
+            .digest('hex');
+        if (actualHash !== parseExpectedSha256(expectedHash, relativePath)) {
+            throw new CliError(`Selected project recap hash verification failed for \`${relativePath}\`.`);
+        }
+    }
+    return entries.length;
+}
+async function exportSelectedProjectRecap(options, snapshotName, dependencies) {
+    const selectedRun = options.projectRecapRun?.trim();
+    if (!selectedRun) {
+        return null;
+    }
+    const sourceRunRoot = await resolveSelectedProjectRecapRun(options.projectPath, selectedRun);
+    const sourceManifestContents = await readFile(join(sourceRunRoot, 'manifest.json'), 'utf8');
+    const sourceManifest = parseProjectRecapManifest(sourceManifestContents);
+    if (sourceManifest.recipe.id !== 'project-recap') {
+        throw new CliError('Selected project recap manifest recipe must be exactly `project-recap`.');
+    }
+    const exportRoot = join(options.repoRoot, '.oat', 'repo', 'reference', 'project-recaps', snapshotName);
+    if (await pathExists(exportRoot)) {
+        throw new CliError(`Project recap export destination \`${exportRoot}\` already exists; refusing to overwrite it.`);
+    }
+    const temporaryRoot = `${exportRoot}.tmp-${randomUUID()}`;
+    const makeDir = dependencies.ensureDir ?? ensureDir;
+    const copyProjectDirectory = dependencies.copyDirectory ?? copyDirectory;
+    const removePath = dependencies.removePath ??
+        (async (target, removeOptions) => rm(target, removeOptions));
+    const renamePath = dependencies.renamePath ?? rename;
+    await makeDir(dirname(exportRoot));
+    try {
+        await copyProjectDirectory(sourceRunRoot, temporaryRoot);
+        const stagedManifestContents = await readFile(join(temporaryRoot, 'manifest.json'), 'utf8');
+        if (stagedManifestContents !== sourceManifestContents) {
+            throw new CliError('Selected project recap manifest changed while staging the export.');
+        }
+        const verifiedArtifactCount = await verifyProjectRecapImmutableHashes(temporaryRoot, sourceManifest);
+        await renamePath(temporaryRoot, exportRoot);
+        return {
+            sourceRunRoot,
+            exportRoot,
+            manifest: {
+                relativePath: 'manifest.json',
+                verifiedArtifactCount,
+            },
+        };
+    }
+    catch (error) {
+        await removePath(temporaryRoot, { recursive: true, force: true });
+        throw error;
+    }
+}
 export async function archiveProjectOnCompletion(options, dependencies = {}) {
     const makeDir = dependencies.ensureDir ?? ensureDir;
     const copyProjectDirectory = dependencies.copyDirectory ?? copyDirectory;
@@ -296,13 +595,25 @@ export async function archiveProjectOnCompletion(options, dependencies = {}) {
     }, dependencies);
     assertDurableArchiveProjectTarget(archiveTarget);
     const archivePath = archiveTarget.archivePath;
-    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 projectRecapExport = await exportSelectedProjectRecap(options, snapshotName, dependencies);
+    try {
+        await makeDir(dirname(archivePath));
+        await copyProjectDirectory(options.projectPath, archivePath);
+        await writeArchiveSnapshotMetadata(archivePath, {
+            projectName: options.projectName,
+            snapshotName,
+        });
+        await removePath(options.projectPath, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (projectRecapExport) {
+            await removePath(projectRecapExport.exportRoot, {
+                recursive: true,
+                force: true,
+            });
+        }
+        throw error;
+    }
     const warnings = [];
     let summaryExportFile = null;
     if (options.summaryExportPath) {
@@ -354,6 +665,7 @@ export async function archiveProjectOnCompletion(options, dependencies = {}) {
         archivePath,
         s3Path,
         summaryExportFile,
+        projectRecapExport,
         warnings,
     };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAIL,KAAK,qCAAqC,EAC3C,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,iCAAiC,EACvC,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,kBAAkB,EAClB,iCAAiC,GAClC,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qCAAqC,GACtC,MAAM,eAAe,CAAC;AAEvB,KAAK,0BAA0B,GAAG,iCAAiC,GACjE,qCAAqC,CAAC;AAKxC,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAyET"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAIL,KAAK,qCAAqC,EAC3C,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,iCAAiC,EACvC,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,kBAAkB,EAClB,iCAAiC,GAClC,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qCAAqC,GACtC,MAAM,eAAe,CAAC;AAEvB,KAAK,0BAA0B,GAAG,iCAAiC,GACjE,qCAAqC,CAAC;AAKxC,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CA6ET"}

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

@@ -13,6 +13,7 @@ export function createProjectArchiveCommand(overrides = {}) {
         .description('Manage archived project data')
         .argument('[project-path]', 'Project path to archive')
         .option('--dry-run', 'Preview archive without moving files or syncing S3')
+        .option('--project-recap-run <path>', 'Export the selected project-relative recap run before archiving')
         .addHelpText('afterAll', '\nPull archived project data with `oat repo archive sync [project-name]`; `oat project archive sync` is deprecated.')
         .action(async (projectPath, options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));

package/dist/commands/project/archive/push-runner.d.ts

@@ -3,6 +3,7 @@ import { type OatConfig, type OatLocalConfig } from '../../../config/oat-config.
 import { resolveArchiveProjectTarget, resolvePrimaryRepoRoot, type ArchiveProjectOnCompletionOptions, type ArchiveProjectOnCompletionResult } from './archive-utils.js';
 export interface ArchivePushOptions {
     dryRun?: boolean;
+    projectRecapRun?: string;
 }
 export interface ProjectArchivePushCommandDependencies {
     buildCommandContext: (options: Parameters<typeof buildCommandContext>[0]) => CommandContext;

package/dist/commands/project/archive/push-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"push-runner.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/push-runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAKL,2BAA2B,EAC3B,sBAAsB,EAEtB,KAAK,iCAAiC,EACtC,KAAK,gCAAgC,EACtC,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,qCAAqC;IACpD,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,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;IAChE,0BAA0B,EAAE,CAC1B,OAAO,EAAE,iCAAiC,KACvC,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,SAAS,EAAE,MAAM,MAAM,CAAC;CACzB;AAkBD,wBAAgB,4CAA4C,IAAI,qCAAqC,CAapG;AA2ID,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,qCAAqC,EACnD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAiEf"}
+{"version":3,"file":"push-runner.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/archive/push-runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAKL,2BAA2B,EAC3B,sBAAsB,EAEtB,KAAK,iCAAiC,EACtC,KAAK,gCAAgC,EAEtC,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qCAAqC;IACpD,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,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;IAChE,0BAA0B,EAAE,CAC1B,OAAO,EAAE,iCAAiC,KACvC,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,SAAS,EAAE,MAAM,MAAM,CAAC;CACzB;AAmBD,wBAAgB,4CAA4C,IAAI,qCAAqC,CAapG;AAkJD,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,qCAAqC,EACnD,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAoEf"}

package/dist/commands/project/archive/push-runner.js

@@ -40,7 +40,7 @@ async function resolveArchiveTarget(dependencies, repoRoot, projectPathArg) {
         projectPath: absoluteProjectPath,
     };
 }
-function buildArchiveOptions(repoRoot, config, projectsRoot, target) {
+function buildArchiveOptions(repoRoot, config, projectsRoot, target, options) {
     return {
         repoRoot,
         projectPath: target.projectPath,
@@ -49,6 +49,7 @@ function buildArchiveOptions(repoRoot, config, projectsRoot, target) {
         s3Uri: config.archive?.s3Uri,
         s3SyncOnComplete: config.archive?.s3SyncOnComplete ?? false,
         summaryExportPath: config.archive?.summaryExportPath,
+        projectRecapRun: options.projectRecapRun,
         awsProfile: config.archive?.awsProfile,
         awsRegion: config.archive?.awsRegion,
     };
@@ -94,6 +95,9 @@ function emitArchivePushText(report, summaryExportPath, logger) {
     if (report.summaryExportFile) {
         logger.info(`Summary export: ${report.summaryExportFile}`);
     }
+    if (report.projectRecapExport) {
+        logger.info(`Project recap export: ${report.projectRecapExport.exportRoot}`);
+    }
 }
 function emitArchivePushReport(report, summaryExportPath, context) {
     if (context.json) {
@@ -124,7 +128,7 @@ export async function runArchivePushCommand(dependencies, projectPathArg, option
             process.exitCode = 0;
             return;
         }
-        const result = await dependencies.archiveProjectOnCompletion(buildArchiveOptions(repoRoot, config, projectsRoot, target));
+        const result = await dependencies.archiveProjectOnCompletion(buildArchiveOptions(repoRoot, config, projectsRoot, target, options));
         const report = {
             status: 'ok',
             mode: 'apply',
@@ -133,6 +137,9 @@ export async function runArchivePushCommand(dependencies, projectPathArg, option
             archivePath: result.archivePath,
             s3Path: result.s3Path,
             summaryExportFile: result.summaryExportFile,
+            ...(result.projectRecapExport
+                ? { projectRecapExport: result.projectRecapExport }
+                : {}),
             warnings: result.warnings,
         };
         emitArchivePushReport(report, config.archive?.summaryExportPath, context);

package/dist/config/oat-config.d.ts

@@ -18,6 +18,23 @@ export interface OatArchiveConfig {
     awsProfile?: string;
     awsRegion?: string;
 }
+export interface OatExplainerDefaultsConfig {
+    palette?: string;
+    visualProfile?: string;
+    themeBundlePath?: string;
+}
+export type OatExplainerPublishProvider = 's3-static';
+export interface OatExplainerPublishConfig {
+    provider?: OatExplainerPublishProvider;
+    s3Uri?: string;
+    publicBaseUrl?: string;
+    awsRegion?: string;
+    awsProfile?: string;
+}
+export interface OatExplainersConfig {
+    defaults?: OatExplainerDefaultsConfig;
+    publish?: OatExplainerPublishConfig;
+}
 export type WorkflowHillCheckpointDefault = 'every' | 'final';
 export type WorkflowProjectLog = true | false | 'auto';
 export type WorkflowPostImplementStep = 'summary' | 'document' | 'pr';
@@ -52,6 +69,11 @@ export interface WorkflowAutoArtifactReview {
     plan?: boolean;
     analysis?: boolean;
 }
+export type WorkflowExplainerPreference = 'always' | 'ask' | 'never';
+export interface WorkflowExplainersConfig {
+    projectExplainer?: WorkflowExplainerPreference;
+    projectRecap?: WorkflowExplainerPreference;
+}
 export interface GateConfig {
     command: string;
     onFailure: GateOnFailure;
@@ -97,6 +119,7 @@ export interface OatWorkflowConfig {
     dispatchCeiling?: WorkflowDispatchCeiling;
     gateTimeouts?: WorkflowGateTimeouts;
     gates?: WorkflowGatesConfig;
+    explainers?: WorkflowExplainersConfig;
 }
 export declare const VALID_CODEX_DISPATCH_CEILINGS: readonly WorkflowCodexDispatchCeiling[];
 export declare const VALID_CLAUDE_DISPATCH_CEILINGS: readonly WorkflowClaudeDispatchCeiling[];
@@ -117,6 +140,7 @@ export interface OatConfig {
     };
     git?: OatGitConfig;
     archive?: OatArchiveConfig;
+    explainers?: OatExplainersConfig;
     tools?: OatToolsConfig;
     documentation?: OatDocumentationConfig;
     localPaths?: string[];
@@ -128,12 +152,14 @@ export interface OatLocalConfig {
     activeProject?: string | null;
     lastPausedProject?: string | null;
     activeIdea?: string | null;
+    explainers?: OatExplainersConfig;
     workflow?: OatWorkflowConfig;
 }
 export interface UserConfig {
     version: number;
     activeIdea?: string | null;
     updateNotifications?: boolean;
+    explainers?: OatExplainersConfig;
     workflow?: OatWorkflowConfig;
 }
 export interface ActiveProjectResolution {

package/dist/config/oat-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oat-config.d.ts","sourceRoot":"","sources":["../../src/config/oat-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oat-config.d.ts","sourceRoot":"","sources":["../../src/config/oat-config.ts"],"names":[],"mappings":"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"}

package/dist/config/oat-config.js

@@ -41,6 +41,7 @@ const VALID_DESIGN_MODES = [
     'selective',
     'draft',
 ];
+const VALID_WORKFLOW_EXPLAINER_PREFERENCES = ['always', 'ask', 'never'];
 export const VALID_CODEX_DISPATCH_CEILINGS = ['low', 'medium', 'high', 'xhigh', 'max'];
 export const VALID_CLAUDE_DISPATCH_CEILINGS = ['haiku', 'sonnet', 'opus', 'fable'];
 export const VALID_DISPATCH_CEILING_PRESETS = ['balanced', 'maximum', 'cost-conscious'];
@@ -244,6 +245,68 @@ function normalizeRecordMap(value, normalizeValue) {
     }
     return Object.keys(next).length > 0 ? next : undefined;
 }
+function normalizeExplainersConfig(parsed, scope) {
+    if (!isRecord(parsed)) {
+        return undefined;
+    }
+    const next = {};
+    if (isRecord(parsed.defaults)) {
+        const defaults = {};
+        const palette = trimNonEmptyString(parsed.defaults.palette);
+        if (palette !== undefined) {
+            defaults.palette = palette;
+        }
+        const visualProfile = trimNonEmptyString(parsed.defaults.visualProfile);
+        if (visualProfile !== undefined) {
+            defaults.visualProfile = visualProfile;
+        }
+        if (scope !== 'user') {
+            const rawPath = trimNonEmptyString(parsed.defaults.themeBundlePath);
+            if (rawPath !== undefined) {
+                const normalizedPath = normalizeToPosixPath(rawPath);
+                const escapesSharedScope = normalizedPath === '..' || normalizedPath.startsWith('../');
+                if (scope === 'local' ||
+                    (!isAbsolute(normalizedPath) && !escapesSharedScope)) {
+                    defaults.themeBundlePath = normalizedPath;
+                }
+            }
+        }
+        if (Object.keys(defaults).length > 0) {
+            next.defaults = defaults;
+        }
+    }
+    if (isRecord(parsed.publish)) {
+        const publish = {};
+        if (scope === 'shared') {
+            if (parsed.publish.provider === 's3-static') {
+                publish.provider = 's3-static';
+            }
+            const s3Uri = trimNonEmptyString(parsed.publish.s3Uri);
+            if (s3Uri !== undefined && /^s3:\/\/[^/\s]+(?:\/.*)?$/.test(s3Uri)) {
+                publish.s3Uri = s3Uri.replace(/\/+$/, '');
+            }
+            const publicBaseUrl = trimNonEmptyString(parsed.publish.publicBaseUrl);
+            if (publicBaseUrl !== undefined &&
+                /^https:\/\/[^/\s]+(?:\/.*)?$/.test(publicBaseUrl)) {
+                publish.publicBaseUrl = publicBaseUrl.replace(/\/+$/, '');
+            }
+            const awsRegion = trimNonEmptyString(parsed.publish.awsRegion);
+            if (awsRegion !== undefined) {
+                publish.awsRegion = awsRegion;
+            }
+        }
+        else {
+            const awsProfile = trimNonEmptyString(parsed.publish.awsProfile);
+            if (awsProfile !== undefined) {
+                publish.awsProfile = awsProfile;
+            }
+        }
+        if (Object.keys(publish).length > 0) {
+            next.publish = publish;
+        }
+    }
+    return Object.keys(next).length > 0 ? next : undefined;
+}
 function normalizeWorkflowConfig(parsed) {
     if (!isRecord(parsed)) {
         return undefined;
@@ -368,6 +431,19 @@ function normalizeWorkflowConfig(parsed) {
             next.gates = gates;
         }
     }
+    if (isRecord(parsed.explainers)) {
+        const explainers = {};
+        for (const key of ['projectExplainer', 'projectRecap']) {
+            const value = parsed.explainers[key];
+            if (typeof value === 'string' &&
+                VALID_WORKFLOW_EXPLAINER_PREFERENCES.includes(value)) {
+                explainers[key] = value;
+            }
+        }
+        if (Object.keys(explainers).length > 0) {
+            next.explainers = explainers;
+        }
+    }
     return Object.keys(next).length > 0 ? next : undefined;
 }
 const DEFAULT_OAT_CONFIG = { version: 1 };
@@ -496,6 +572,10 @@ function normalizeOatConfig(parsed) {
             next.archive = archive;
         }
     }
+    const explainers = normalizeExplainersConfig(parsed.explainers, 'shared');
+    if (explainers) {
+        next.explainers = explainers;
+    }
     if (isRecord(parsed.tools)) {
         const validPacks = [
             'core',
@@ -582,6 +662,10 @@ function normalizeOatLocalConfig(repoRoot, parsed) {
                 ? parsed.activeIdea.trim()
                 : null;
     }
+    const explainers = normalizeExplainersConfig(parsed.explainers, 'local');
+    if (explainers) {
+        next.explainers = explainers;
+    }
     const workflow = normalizeWorkflowConfig(parsed.workflow);
     if (workflow) {
         next.workflow = workflow;
@@ -721,6 +805,10 @@ function normalizeUserConfig(parsed) {
     if (typeof parsed.updateNotifications === 'boolean') {
         next.updateNotifications = parsed.updateNotifications;
     }
+    const explainers = normalizeExplainersConfig(parsed.explainers, 'user');
+    if (explainers) {
+        next.explainers = explainers;
+    }
     const workflow = normalizeWorkflowConfig(parsed.workflow);
     if (workflow) {
         next.workflow = workflow;

package/dist/config/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/config/resolve.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR,OAAO,GACP,MAAM,GACN,KAAK,GACL,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,kCAAkC;IACjD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAChE;AAsFD,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,GAAE,OAAO,CAAC,kCAAkC,CAAM,GAC1D,OAAO,CAAC,cAAc,CAAC,CAgFzB;AAED,wBAAgB,WAAW,CACzB,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,MAAM,GAChB,UAAU,GAAG,IAAI,CAcnB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAY5B;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAoDxC"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/config/resolve.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR,OAAO,GACP,MAAM,GACN,KAAK,GACL,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,kCAAkC;IACjD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAChE;AAwGD,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,GAAE,OAAO,CAAC,kCAAkC,CAAM,GAC1D,OAAO,CAAC,cAAc,CAAC,CAgFzB;AAED,wBAAgB,WAAW,CACzB,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE,MAAM,GAChB,UAAU,GAAG,IAAI,CAcnB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAY5B;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvE,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAoDxC"}