shift-ax 0.3.0

package/dist/scripts/ax-run-request.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { stderr, stdin } from 'node:process';
+import { getPlatformAdapter } from '../adapters/index.js';
+import { resolveContextFromIndex } from '../core/context/index-resolver.js';
+import { orchestrateExecutionTasks } from '../core/planning/execution-orchestrator.js';
+import { resumeRequestPipeline, startRequestPipeline, } from '../core/planning/request-pipeline.js';
+import { buildPlanningArtifactsFromInterview, } from '../core/planning/brainstorm.js';
+import { parseEscalationArgument } from '../core/planning/escalation.js';
+import { defaultEngineeringDefaults, readProjectProfile, } from '../core/policies/project-profile.js';
+import { getGlobalContextHome } from '../core/settings/global-context-home.js';
+function usage() {
+    process.stderr.write([
+        'Usage:',
+        '  ax-run-request --request "<text>" [--summary "<text>"] [--brainstorm-file PATH] [--spec-file PATH] [--plan-file PATH] [--index PATH] [--root DIR] [--base BRANCH]',
+        '  ax-run-request --topic DIR --resume [--platform <codex|claude-code>] [--verify-command CMD]... [--escalation KIND[:summary]]... [--clear-escalations] [--escalation-resolution "<text>"] [--no-auto-commit]',
+        '',
+    ].join('\n'));
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+function readArgs(flag) {
+    const values = [];
+    process.argv.forEach((arg, index) => {
+        if (arg === flag && process.argv[index + 1]) {
+            values.push(process.argv[index + 1]);
+        }
+    });
+    return values;
+}
+async function readMaybeFile(path) {
+    if (!path)
+        return undefined;
+    const { readFile } = await import('node:fs/promises');
+    return readFile(path, 'utf8');
+}
+async function promptInteractivePlanning(request, matchedContextLabels, rootDir) {
+    const profile = (await readProjectProfile(rootDir)) ?? {
+        engineering_defaults: defaultEngineeringDefaults(),
+    };
+    const fallbackAnswers = !stdin.isTTY
+        ? (await new Promise((resolve, reject) => {
+            let raw = '';
+            stdin.setEncoding('utf8');
+            stdin.on('data', (chunk) => {
+                raw += chunk;
+            });
+            stdin.on('end', () => resolve(raw));
+            stdin.on('error', reject);
+        }))
+            .split(/\r?\n/)
+        : null;
+    let fallbackIndex = 0;
+    const rl = stdin.isTTY
+        ? createInterface({
+            input: stdin,
+            output: stderr,
+        })
+        : null;
+    const ask = async (question) => {
+        if (rl) {
+            return rl.question(question);
+        }
+        stderr.write(question);
+        const answer = fallbackAnswers?.[fallbackIndex] ?? '';
+        fallbackIndex += 1;
+        return answer;
+    };
+    const answers = {
+        outcome: (await ask('Clarified outcome: ')).trim(),
+        constraints: (await ask('Constraints or policy notes: ')).trim(),
+        outOfScope: (await ask('Explicitly out of scope: ')).trim(),
+        verification: (await ask('Verification / tests that should prove this: ')).trim(),
+        implementationAreas: (await ask('Likely implementation areas: ')).trim(),
+        longRunningWork: (await ask('Any long-running or cross-cutting work: ')).trim(),
+        policyUpdates: (await ask('Global knowledge updates to add or refine before implementation: ')).trim(),
+    };
+    rl?.close();
+    return buildPlanningArtifactsFromInterview({
+        request,
+        matchedContextLabels,
+        answers,
+        engineeringDefaults: profile.engineering_defaults,
+    });
+}
+async function resolveMatchedContextLabels(rootDir, query, indexPath) {
+    const home = getGlobalContextHome();
+    const effectiveIndexPath = indexPath || (existsSync(home.indexPath) ? home.indexPath : `${rootDir}/docs/base-context/index.md`);
+    if (!existsSync(effectiveIndexPath)) {
+        return [];
+    }
+    const resolved = await resolveContextFromIndex({
+        rootDir,
+        indexPath: effectiveIndexPath,
+        indexRootDir: effectiveIndexPath === home.indexPath ? home.root : rootDir,
+        query,
+    });
+    return resolved.matches.map((match) => match.label);
+}
+function buildContextResolutionQuery({ request, brainstormContent, specContent, implementationPlanContent, }) {
+    return [
+        request.trim(),
+        brainstormContent?.trim() ?? '',
+        specContent?.trim() ?? '',
+        implementationPlanContent?.trim() ?? '',
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+}
+async function main() {
+    const topicDir = readArg('--topic');
+    const resume = process.argv.includes('--resume');
+    const platform = readArg('--platform');
+    if (resume) {
+        if (!topicDir) {
+            usage();
+            process.exit(1);
+        }
+        if (platform && platform !== 'codex' && platform !== 'claude-code') {
+            usage();
+            process.exit(1);
+        }
+        const runtimePlatform = platform === 'codex' || platform === 'claude-code' ? platform : undefined;
+        const executionRunner = runtimePlatform
+            ? async ({ topicDir }) => {
+                const adapter = getPlatformAdapter(runtimePlatform);
+                const plan = await adapter.planExecution({ topicDir });
+                return orchestrateExecutionTasks({
+                    topicDir,
+                    tasks: plan.tasks,
+                    runTask: async (task) => {
+                        await adapter.launchExecution({
+                            topicDir,
+                            taskId: task.task_id,
+                        });
+                    },
+                });
+            }
+            : undefined;
+        const result = await resumeRequestPipeline({
+            topicDir,
+            verificationCommands: readArgs('--verify-command'),
+            escalationTriggers: readArgs('--escalation').map((value) => parseEscalationArgument(value)),
+            clearEscalations: process.argv.includes('--clear-escalations'),
+            escalationResolution: readArg('--escalation-resolution'),
+            autoCommit: !process.argv.includes('--no-auto-commit'),
+            executionRunner,
+        });
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    const request = readArg('--request');
+    if (!request) {
+        usage();
+        process.exit(1);
+    }
+    const rootDir = readArg('--root') || process.cwd();
+    const indexPath = readArg('--index');
+    const allowMissingGlobalIndex = process.argv.includes('--allow-missing-global-context');
+    let brainstormContent = await readMaybeFile(readArg('--brainstorm-file'));
+    let specContent = await readMaybeFile(readArg('--spec-file'));
+    let implementationPlanContent = await readMaybeFile(readArg('--plan-file'));
+    if (!brainstormContent && !specContent && !implementationPlanContent) {
+        const matchedContextLabels = await resolveMatchedContextLabels(rootDir, request, indexPath);
+        const generated = await promptInteractivePlanning(request, matchedContextLabels, rootDir);
+        brainstormContent = generated.brainstormContent;
+        specContent = generated.specContent;
+        implementationPlanContent = generated.implementationPlanContent;
+    }
+    const contextQuery = buildContextResolutionQuery({
+        request,
+        brainstormContent,
+        specContent,
+        implementationPlanContent,
+    });
+    const result = await startRequestPipeline({
+        rootDir,
+        request,
+        summary: readArg('--summary'),
+        indexPath,
+        contextQuery,
+        brainstormContent,
+        specContent,
+        implementationPlanContent,
+        baseBranch: readArg('--base') || 'main',
+        allowMissingGlobalIndex,
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+void main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/scripts/ax-scaffold-build.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { scaffoldPlatformBuild } from '../platform/scaffold.js';
+function usage() {
+    process.stderr.write('Usage: ax-scaffold-build --platform <codex|claude-code> [--root DIR]\n');
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const platform = readArg('--platform');
+const rootDir = readArg('--root') || process.cwd();
+if (platform !== 'codex' && platform !== 'claude-code') {
+    usage();
+    process.exit(1);
+}
+const result = await scaffoldPlatformBuild({ platform, rootDir });
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/dist/scripts/ax-shell.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { isProjectOnboarded, launchPlatformShell, resolveShellDefaultFullAuto, resolveShellLocale, persistShellSettings, } from '../core/shell/platform-shell.js';
+import { onboardProjectContext, onboardProjectContextFromDiscovery } from '../core/context/onboarding.js';
+import { readProjectSettings } from '../core/settings/project-settings.js';
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+function usage() {
+    process.stderr.write([
+        'Usage:',
+        '  shift-ax --codex [--root DIR] [--lang en|ko] [--full-auto] [--discover] [--overwrite] [--onboarding-input FILE] [initial prompt]',
+        '  shift-ax --claude-code [--root DIR] [--lang en|ko] [--full-auto] [--discover] [--overwrite] [--onboarding-input FILE] [initial prompt]',
+        '  shift-ax  # default product shell launcher (Codex unless global settings say otherwise)',
+        '',
+    ].join('\n'));
+}
+function parsePlatform() {
+    if (process.argv.includes('--codex'))
+        return 'codex';
+    if (process.argv.includes('--claude-code'))
+        return 'claude-code';
+    return undefined;
+}
+function parseLocale() {
+    const locale = readArg('--lang');
+    return locale === 'en' || locale === 'ko' ? locale : undefined;
+}
+function collectPromptArgs() {
+    const ignored = new Set([
+        '--codex',
+        '--claude-code',
+        '--full-auto',
+        '--discover',
+        '--overwrite',
+        '--lang',
+        '--root',
+        '--onboarding-input',
+    ]);
+    const values = process.argv.slice(2);
+    const result = [];
+    for (let index = 0; index < values.length; index += 1) {
+        const token = values[index];
+        if (ignored.has(token)) {
+            if (token === '--lang' || token === '--root' || token === '--onboarding-input') {
+                index += 1;
+            }
+            continue;
+        }
+        result.push(token);
+    }
+    return result.join(' ').trim();
+}
+const rootDir = readArg('--root') || process.cwd();
+const requestedPlatform = parsePlatform();
+const requestedLocale = parseLocale();
+const onboardingInput = readArg('--onboarding-input');
+const discover = process.argv.includes('--discover');
+const overwrite = process.argv.includes('--overwrite');
+const requestedFullAuto = process.argv.includes('--full-auto');
+const prompt = collectPromptArgs();
+const existingSettings = await readProjectSettings(rootDir);
+const onboarded = await isProjectOnboarded(rootDir);
+if ((requestedLocale === undefined && process.argv.includes('--lang')) || process.argv.includes('--help')) {
+    usage();
+    process.exit(process.argv.includes('--help') ? 0 : 1);
+}
+const locale = await resolveShellLocale({
+    rootDir,
+    requestedLocale,
+});
+const platform = requestedPlatform ??
+    existingSettings?.preferred_platform ??
+    'codex';
+const defaultFullAuto = await resolveShellDefaultFullAuto({
+    rootDir,
+    locale,
+});
+const effectiveFullAuto = defaultFullAuto || requestedFullAuto;
+if (!onboarded) {
+    if (onboardingInput) {
+        await onboardProjectContext({
+            ...JSON.parse(await readFile(onboardingInput, 'utf8')),
+            rootDir,
+            overwrite,
+        });
+        await persistShellSettings({
+            rootDir,
+            locale,
+            defaultFullAuto,
+            platform,
+        });
+    }
+    else if (discover) {
+        await onboardProjectContextFromDiscovery({
+            rootDir,
+            includeGlossary: true,
+            overwrite,
+        });
+        await persistShellSettings({
+            rootDir,
+            locale,
+            defaultFullAuto,
+            platform,
+        });
+    }
+}
+await persistShellSettings({
+    rootDir,
+    locale,
+    defaultFullAuto,
+    platform,
+});
+const exitCode = await launchPlatformShell({
+    rootDir,
+    platform,
+    fullAuto: effectiveFullAuto,
+    ...(prompt ? { initialPrompt: prompt } : {}),
+});
+process.exit(exitCode);

package/dist/scripts/ax-sync-policy-context.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { completePolicyContextSync } from '../core/planning/policy-context-sync.js';
+function usage() {
+    process.stderr.write('Usage: ax-sync-policy-context --topic DIR --summary "<text>" [--path REL_PATH]... [--entry "Label -> path"]...\n');
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+function readArgs(flag) {
+    const values = [];
+    process.argv.forEach((arg, index) => {
+        if (arg === flag && process.argv[index + 1]) {
+            values.push(process.argv[index + 1]);
+        }
+    });
+    return values;
+}
+function parseEntry(value) {
+    const [label, path] = value.split('->').map((part) => part.trim());
+    if (!label || !path) {
+        throw new Error(`invalid --entry value: ${value}`);
+    }
+    return { label, path };
+}
+const topicDir = readArg('--topic');
+const summary = readArg('--summary');
+if (!topicDir || !summary) {
+    usage();
+    process.exit(1);
+}
+const result = await completePolicyContextSync({
+    topicDir,
+    summary,
+    syncedPaths: readArgs('--path'),
+    syncedEntries: readArgs('--entry').map(parseEntry),
+});
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/dist/scripts/ax-team-preferences.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { readTeamPreferences, writeTeamPreferences } from '../core/policies/team-preferences.js';
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const rootDir = readArg('--root') || process.cwd();
+const inputPath = readArg('--input');
+if (inputPath) {
+    const raw = await readFile(inputPath, 'utf8');
+    await writeTeamPreferences({
+        rootDir,
+        preferences: JSON.parse(raw),
+    });
+}
+const result = await readTeamPreferences(rootDir);
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/dist/scripts/ax-thread-save.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { saveThreadNote } from '../core/memory/threads.js';
+function usage() {
+    process.stderr.write('Usage: ax-thread-save --root DIR --name NAME [--summary "<text>"] --note "<text>"\n');
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const rootDir = readArg('--root') || process.cwd();
+const name = readArg('--name');
+const summary = readArg('--summary');
+const note = readArg('--note');
+if (!name || !note) {
+    usage();
+    process.exit(1);
+}
+const result = await saveThreadNote({
+    rootDir,
+    name,
+    ...(summary ? { summary } : {}),
+    note,
+});
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/dist/scripts/ax-threads.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { listThreads } from '../core/memory/threads.js';
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const rootDir = readArg('--root') || process.cwd();
+const result = await listThreads({ rootDir });
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/dist/scripts/ax-topic-status.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { summarizeTopicStatus } from '../core/observability/topic-status.js';
+function usage() {
+    process.stderr.write('Usage: ax-topic-status --topic DIR\n');
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const topicDir = readArg('--topic');
+if (!topicDir) {
+    usage();
+    process.exit(1);
+}
+const summary = await summarizeTopicStatus(topicDir);
+process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);

package/dist/scripts/ax-topics-status.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { listTopicsStatus } from '../core/observability/topics-status.js';
+function usage() {
+    process.stderr.write('Usage: ax-topics-status [--root DIR] [--limit N]\n');
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const rootDir = readArg('--root') || process.cwd();
+const limit = Number(readArg('--limit') || '10');
+if (process.argv.includes('--help')) {
+    usage();
+    process.exit(0);
+}
+const result = await listTopicsStatus({
+    rootDir,
+    limit: Number.isFinite(limit) && limit > 0 ? limit : 10,
+});
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/dist/scripts/ax-verification-debt.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { listVerificationDebt } from '../core/observability/verification-debt.js';
+function usage() {
+    process.stderr.write('Usage: ax-verification-debt [--root DIR] [--topic DIR]\n');
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const rootDir = readArg('--root');
+const topicDir = readArg('--topic');
+if (!rootDir && !topicDir) {
+    usage();
+    process.exit(1);
+}
+const result = await listVerificationDebt({
+    ...(rootDir ? { rootDir } : {}),
+    ...(topicDir ? { topicDir } : {}),
+});
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/dist/scripts/ax-worktree-create.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { createTopicWorktree } from '../core/topics/worktree-runtime.js';
+function usage() {
+    process.stderr.write('Usage: ax-worktree-create --topic DIR [--base BRANCH]\n');
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const topicDir = readArg('--topic');
+const baseBranch = readArg('--base') || 'main';
+if (!topicDir) {
+    usage();
+    process.exit(1);
+}
+const result = await createTopicWorktree({
+    topicDir,
+    baseBranch,
+});
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/dist/scripts/ax-worktree-plan.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { planTopicWorktree } from '../core/topics/worktree-runtime.js';
+function usage() {
+    process.stderr.write('Usage: ax-worktree-plan --topic DIR\n');
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const topicDir = readArg('--topic');
+if (!topicDir) {
+    usage();
+    process.exit(1);
+}
+const plan = await planTopicWorktree({ topicDir });
+process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);

package/dist/scripts/ax-worktree-remove.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { removeTopicWorktree } from '../core/topics/worktree-runtime.js';
+function usage() {
+    process.stderr.write('Usage: ax-worktree-remove --topic DIR\n');
+}
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+const topicDir = readArg('--topic');
+if (!topicDir) {
+    usage();
+    process.exit(1);
+}
+const result = await removeTopicWorktree({ topicDir });
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);