@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.1400

package/dist/lib/spinner.js

@@ -0,0 +1,76 @@
+/**
+ * Contextual spinner for async operations.
+ * WP-303 Slice 2: Ambient Feedback (Spinners).
+ *
+ * - TTY: shows animated spinner with 200ms delayed start
+ * - Non-TTY / quiet / json: silent (no output)
+ * - On success: replaces spinner with success message
+ * - On failure: replaces spinner with failure message, rethrows
+ *
+ * Uses raw ANSI escape codes to stay consistent with style.ts (no @clack dependency).
+ */
+import { isQuietMode, isJsonMode } from './runner.js';
+import { green, red, icons } from './style.js';
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const FRAME_INTERVAL_MS = 80;
+const DELAYED_START_MS = 200;
+/** Returns true if spinner output should be suppressed. */
+function isSilent() {
+    return !process.stdout.isTTY || isQuietMode() || isJsonMode();
+}
+/**
+ * Run an async function with a contextual spinner.
+ *
+ * In interactive TTY mode, a spinner appears after 200ms (avoids flicker for
+ * fast operations). In non-TTY / quiet / JSON mode, the function runs silently.
+ *
+ * @param label - Text shown next to the spinner (e.g. "Loading orient data")
+ * @param fn - The async operation to run
+ * @param options.successMessage - Optional override for the completion message
+ * @returns The result of fn()
+ * @throws Rethrows any error from fn() after displaying failure
+ */
+export async function withSpinner(label, fn, options) {
+    // Non-interactive: just run the function
+    if (isSilent()) {
+        return fn();
+    }
+    let frameIndex = 0;
+    let spinnerInterval;
+    let started = false;
+    const write = (text) => {
+        // Clear line and write
+        process.stderr.write(`\r\x1b[K${text}`);
+    };
+    const startSpinner = () => {
+        started = true;
+        spinnerInterval = setInterval(() => {
+            const frame = SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length];
+            write(`${frame} ${label}`);
+            frameIndex++;
+        }, FRAME_INTERVAL_MS);
+    };
+    // Delayed start — avoids spinner flash for fast operations
+    const delayTimer = setTimeout(startSpinner, DELAYED_START_MS);
+    try {
+        const result = await fn();
+        clearTimeout(delayTimer);
+        if (spinnerInterval)
+            clearInterval(spinnerInterval);
+        if (started) {
+            const msg = options?.successMessage || label;
+            write(`${green(icons.pass)} ${msg}\n`);
+        }
+        return result;
+    }
+    catch (err) {
+        clearTimeout(delayTimer);
+        if (spinnerInterval)
+            clearInterval(spinnerInterval);
+        if (started) {
+            write(`${red(icons.fail)} ${label} \u2014 failed\n`);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=spinner.js.map

package/dist/lib/spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.js","sourceRoot":"","sources":["../../src/lib/spinner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAC1E,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAC7B,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B,2DAA2D;AAC3D,SAAS,QAAQ;IACf,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,WAAW,EAAE,IAAI,UAAU,EAAE,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAa,EACb,EAAoB,EACpB,OAAqC;IAErC,yCAAyC;IACzC,IAAI,QAAQ,EAAE,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAED,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,eAA2D,CAAC;IAChE,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,EAAE;QAC7B,uBAAuB;QACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,GAAG,EAAE;QACxB,OAAO,GAAG,IAAI,CAAC;QACf,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE;YACjC,MAAM,KAAK,GAAG,cAAc,CAAC,UAAU,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;YACjE,KAAK,CAAC,GAAG,KAAK,IAAI,KAAK,EAAE,CAAC,CAAC;YAC3B,UAAU,EAAE,CAAC;QACf,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACxB,CAAC,CAAC;IAEF,2DAA2D;IAC3D,MAAM,UAAU,GAAG,UAAU,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAC1B,YAAY,CAAC,UAAU,CAAC,CAAC;QACzB,IAAI,eAAe;YAAE,aAAa,CAAC,eAAe,CAAC,CAAC;QACpD,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,GAAG,GAAG,OAAO,EAAE,cAAc,IAAI,KAAK,CAAC;YAC7C,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QACzC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,YAAY,CAAC,UAAU,CAAC,CAAC;QACzB,IAAI,eAAe;YAAE,aAAa,CAAC,eAAe,CAAC,CAAC;QACpD,IAAI,OAAO,EAAE,CAAC;YACZ,KAAK,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,kBAAkB,CAAC,CAAC;QACvD,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/lib/spinner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spinner.test.d.ts.map

package/dist/lib/spinner.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.test.d.ts","sourceRoot":"","sources":["../../src/lib/spinner.test.ts"],"names":[],"mappings":""}

package/dist/lib/spinner.test.js

@@ -0,0 +1,39 @@
+/**
+ * withSpinner — unit tests.
+ * WP-303 Slice 2: Ambient Feedback (Spinners).
+ *
+ * Tests run in a non-TTY environment (vitest), so the spinner is always silent.
+ * This validates the critical contract: withSpinner is transparent in non-TTY mode.
+ */
+import { describe, expect, it } from 'vitest';
+import { withSpinner } from './spinner.js';
+describe('withSpinner', () => {
+    it('returns the function result in non-TTY mode', async () => {
+        const result = await withSpinner('Loading', async () => 42);
+        expect(result).toBe(42);
+    });
+    it('returns complex objects unchanged', async () => {
+        const data = { entries: [{ id: 'BET-1', name: 'Test' }], total: 1 };
+        const result = await withSpinner('Loading', async () => data);
+        expect(result).toEqual(data);
+    });
+    it('rethrows errors from the wrapped function', async () => {
+        const err = new Error('network failure');
+        await expect(withSpinner('Loading', async () => {
+            throw err;
+        })).rejects.toThrow('network failure');
+    });
+    it('passes through the success message option without affecting result', async () => {
+        const result = await withSpinner('Loading', async () => 'done', { successMessage: 'Loaded successfully' });
+        expect(result).toBe('done');
+    });
+    it('completes without hanging on fast operations', async () => {
+        // This validates the 200ms delay timer is properly cleaned up
+        const start = Date.now();
+        await withSpinner('Fast op', async () => 'quick');
+        const elapsed = Date.now() - start;
+        // Should complete well under the 200ms delay threshold
+        expect(elapsed).toBeLessThan(100);
+    });
+});
+//# sourceMappingURL=spinner.test.js.map

package/dist/lib/spinner.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.test.js","sourceRoot":"","sources":["../../src/lib/spinner.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;QAC3D,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5D,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,KAAK,IAAI,EAAE;QACjD,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACpE,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;QAC9D,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QACzD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACzC,MAAM,MAAM,CACV,WAAW,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;YAChC,MAAM,GAAG,CAAC;QACZ,CAAC,CAAC,CACH,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oEAAoE,EAAE,KAAK,IAAI,EAAE;QAClF,MAAM,MAAM,GAAG,MAAM,WAAW,CAC9B,SAAS,EACT,KAAK,IAAI,EAAE,CAAC,MAAM,EAClB,EAAE,cAAc,EAAE,qBAAqB,EAAE,CAC1C,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;QAC5D,8DAA8D;QAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,WAAW,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QACnC,uDAAuD;QACvD,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/lib/startup-resolution-signals.d.ts

@@ -0,0 +1,34 @@
+export declare const STARTUP_RESOLUTION_SIGNAL_FIELDS: readonly ["taskText", "explicitScope", "changedPaths", "reviewedArtifactRefs", "branchName", "worktreeName", "sourceSurface", "resolverVersion", "changeId", "commitSha"];
+export declare const STARTUP_RESOLUTION_SIGNAL_SOURCE_SURFACES: readonly ["cli", "mcp", "app", "rest", "internal", "api"];
+export declare const STARTUP_RESOLUTION_SIGNAL_LIMITS: {
+    readonly arrayCaps: {
+        readonly changedPaths: 25;
+        readonly reviewedArtifactRefs: 25;
+    };
+    readonly stringCaps: {
+        readonly taskText: 500;
+        readonly explicitScope: 120;
+        readonly path: 240;
+        readonly artifactRef: 120;
+        readonly branchName: 120;
+        readonly worktreeName: 120;
+        readonly resolverVersion: 80;
+        readonly changeId: 120;
+        readonly commitSha: 80;
+    };
+};
+export type StartupResolutionSourceSurface = (typeof STARTUP_RESOLUTION_SIGNAL_SOURCE_SURFACES)[number];
+export type StartupResolutionSignals = {
+    taskText?: string | null;
+    explicitScope?: string | null;
+    changedPaths?: string[];
+    reviewedArtifactRefs?: string[];
+    branchName?: string | null;
+    worktreeName?: string | null;
+    sourceSurface?: StartupResolutionSourceSurface | string;
+    resolverVersion?: string;
+    changeId?: string | null;
+    commitSha?: string | null;
+};
+export declare function sanitizeStartupResolutionSignals(input: Partial<StartupResolutionSignals>): StartupResolutionSignals;
+//# sourceMappingURL=startup-resolution-signals.d.ts.map

package/dist/lib/startup-resolution-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-resolution-signals.d.ts","sourceRoot":"","sources":["../../src/lib/startup-resolution-signals.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gCAAgC,2KAWnC,CAAC;AAEX,eAAO,MAAM,yCAAyC,2DAO5C,CAAC;AAEX,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;CAgBnC,CAAC;AAEX,MAAM,MAAM,8BAA8B,GAAG,CAAC,OAAO,yCAAyC,CAAC,CAAC,MAAM,CAAC,CAAC;AAExG,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE,8BAA8B,GAAG,MAAM,CAAC;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAgDF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,CAAC,wBAAwB,CAAC,GAAG,wBAAwB,CAgCnH"}

package/dist/lib/startup-resolution-signals.js

@@ -0,0 +1,118 @@
+export const STARTUP_RESOLUTION_SIGNAL_FIELDS = [
+    'taskText',
+    'explicitScope',
+    'changedPaths',
+    'reviewedArtifactRefs',
+    'branchName',
+    'worktreeName',
+    'sourceSurface',
+    'resolverVersion',
+    'changeId',
+    'commitSha',
+];
+export const STARTUP_RESOLUTION_SIGNAL_SOURCE_SURFACES = [
+    'cli',
+    'mcp',
+    'app',
+    'rest',
+    'internal',
+    'api',
+];
+export const STARTUP_RESOLUTION_SIGNAL_LIMITS = {
+    arrayCaps: {
+        changedPaths: 25,
+        reviewedArtifactRefs: 25,
+    },
+    stringCaps: {
+        taskText: 500,
+        explicitScope: 120,
+        path: 240,
+        artifactRef: 120,
+        branchName: 120,
+        worktreeName: 120,
+        resolverVersion: 80,
+        changeId: 120,
+        commitSha: 80,
+    },
+};
+function sanitizeString(value, max) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.slice(0, max);
+}
+function sanitizePath(value) {
+    const trimmed = sanitizeString(value, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.path);
+    if (!trimmed)
+        return undefined;
+    const normalized = trimmed.replace(/\\/g, '/').replace(/\/+/g, '/');
+    if (normalized.startsWith('/') || normalized === '~' || normalized.startsWith('~/'))
+        return undefined;
+    const parts = normalized.split('/').filter((part) => part && part !== '.');
+    if (parts.length === 0 || parts.includes('..'))
+        return undefined;
+    const lowerParts = parts.map((part) => part.toLowerCase());
+    if (lowerParts.some((part) => part === '.env' || part.startsWith('.env.') || part.includes('secret') || part.includes('token'))) {
+        return undefined;
+    }
+    return parts.join('/');
+}
+function sanitizeStringArray(values, cap, max, sanitizer = sanitizeString) {
+    if (!Array.isArray(values))
+        return undefined;
+    const out = [];
+    for (const value of values) {
+        const sanitized = sanitizer(value, max);
+        if (!sanitized)
+            continue;
+        out.push(sanitized);
+        if (out.length >= cap)
+            break;
+    }
+    return out.length > 0 ? out : undefined;
+}
+function sanitizeSourceSurface(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    return STARTUP_RESOLUTION_SIGNAL_SOURCE_SURFACES.includes(normalized)
+        ? normalized
+        : undefined;
+}
+export function sanitizeStartupResolutionSignals(input) {
+    const out = {};
+    const taskText = sanitizeString(input.taskText, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.taskText);
+    if (taskText)
+        out.taskText = taskText;
+    const explicitScope = sanitizeString(input.explicitScope, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.explicitScope);
+    if (explicitScope)
+        out.explicitScope = explicitScope;
+    const changedPaths = sanitizeStringArray(input.changedPaths, STARTUP_RESOLUTION_SIGNAL_LIMITS.arrayCaps.changedPaths, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.path, (value) => sanitizePath(value));
+    if (changedPaths)
+        out.changedPaths = changedPaths;
+    const reviewedArtifactRefs = sanitizeStringArray(input.reviewedArtifactRefs, STARTUP_RESOLUTION_SIGNAL_LIMITS.arrayCaps.reviewedArtifactRefs, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.artifactRef);
+    if (reviewedArtifactRefs)
+        out.reviewedArtifactRefs = reviewedArtifactRefs;
+    const branchName = sanitizeString(input.branchName, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.branchName);
+    if (branchName)
+        out.branchName = branchName;
+    const worktreeName = sanitizeString(input.worktreeName, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.worktreeName);
+    if (worktreeName)
+        out.worktreeName = worktreeName;
+    const sourceSurface = sanitizeSourceSurface(input.sourceSurface);
+    if (sourceSurface)
+        out.sourceSurface = sourceSurface;
+    const resolverVersion = sanitizeString(input.resolverVersion, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.resolverVersion);
+    if (resolverVersion)
+        out.resolverVersion = resolverVersion;
+    const changeId = sanitizeString(input.changeId, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.changeId);
+    if (changeId)
+        out.changeId = changeId;
+    const commitSha = sanitizeString(input.commitSha, STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps.commitSha);
+    if (commitSha)
+        out.commitSha = commitSha;
+    return out;
+}
+//# sourceMappingURL=startup-resolution-signals.js.map

package/dist/lib/startup-resolution-signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-resolution-signals.js","sourceRoot":"","sources":["../../src/lib/startup-resolution-signals.ts"],"names":[],"mappings":"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"}

package/dist/lib/startup-resolution-signals.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=startup-resolution-signals.test.d.ts.map

package/dist/lib/startup-resolution-signals.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-resolution-signals.test.d.ts","sourceRoot":"","sources":["../../src/lib/startup-resolution-signals.test.ts"],"names":[],"mappings":""}

package/dist/lib/startup-resolution-signals.test.js

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { STARTUP_RESOLUTION_SIGNAL_FIELDS, STARTUP_RESOLUTION_SIGNAL_LIMITS, STARTUP_RESOLUTION_SIGNAL_SOURCE_SURFACES, sanitizeStartupResolutionSignals, } from './startup-resolution-signals.js';
+function loadContract() {
+    return JSON.parse(readFileSync(join(process.cwd(), 'startup-resolution-signals.contract.json'), 'utf8'));
+}
+function loadResolutionFixtures() {
+    return JSON.parse(readFileSync(join(process.cwd(), 'startup-resolution-signals.fixtures.json'), 'utf8'));
+}
+function loadSanitizerCases() {
+    return JSON.parse(readFileSync(join(process.cwd(), 'startup-resolution-signals.sanitizer-cases.json'), 'utf8'));
+}
+describe('StartupResolutionSignals CLI contract', () => {
+    it('matches the shared runtime fixture for fields, caps, and source surfaces', () => {
+        const fixture = loadContract();
+        expect(STARTUP_RESOLUTION_SIGNAL_FIELDS).toEqual(fixture.fields);
+        expect(STARTUP_RESOLUTION_SIGNAL_LIMITS.arrayCaps).toEqual(fixture.arrayCaps);
+        expect(STARTUP_RESOLUTION_SIGNAL_LIMITS.stringCaps).toEqual(fixture.stringCaps);
+        expect(STARTUP_RESOLUTION_SIGNAL_SOURCE_SURFACES).toEqual(fixture.sourceSurface);
+    });
+    it('omits empty values, trims strings, caps arrays, and rejects unsafe paths', () => {
+        const fixture = loadContract();
+        const sanitized = sanitizeStartupResolutionSignals({
+            taskText: ` ${'x'.repeat(fixture.stringCaps.taskText + 10)} `,
+            explicitScope: ' product-design/ux ',
+            changedPaths: [
+                'src//routes/Work.svelte',
+                '~/private.env',
+                '../outside.ts',
+                'config/.env.local',
+                '',
+                ...Array.from({ length: fixture.arrayCaps.changedPaths + 5 }, (_, i) => `packages/cli/src/file-${i}.ts`),
+            ],
+            reviewedArtifactRefs: [
+                ' PR #177 ',
+                '',
+                ...Array.from({ length: fixture.arrayCaps.reviewedArtifactRefs + 5 }, (_, i) => `DEC-${i}`),
+            ],
+            branchName: ' feature/wp462 ',
+            worktreeName: ' wp462-rcrt-activation ',
+            sourceSurface: 'cli',
+            resolverVersion: ' rcrt-v3 ',
+            changeId: ' change-123 ',
+            commitSha: ' abc123 ',
+        });
+        expect(sanitized.taskText).toHaveLength(fixture.stringCaps.taskText);
+        expect(sanitized.explicitScope).toBe('product-design/ux');
+        expect(sanitized.changedPaths).toHaveLength(fixture.arrayCaps.changedPaths);
+        expect(sanitized.changedPaths).toContain('src/routes/Work.svelte');
+        expect(sanitized.changedPaths).not.toContain('~/private.env');
+        expect(sanitized.changedPaths).not.toContain('../outside.ts');
+        expect(sanitized.changedPaths).not.toContain('config/.env.local');
+        expect(sanitized.reviewedArtifactRefs).toHaveLength(fixture.arrayCaps.reviewedArtifactRefs);
+        expect(sanitized.reviewedArtifactRefs?.[0]).toBe('PR #177');
+        expect(sanitized.branchName).toBe('feature/wp462');
+        expect(sanitized.worktreeName).toBe('wp462-rcrt-activation');
+        expect(sanitized.sourceSurface).toBe('cli');
+        expect(sanitized.resolverVersion).toBe('rcrt-v3');
+        expect(sanitized.changeId).toBe('change-123');
+        expect(sanitized.commitSha).toBe('abc123');
+    });
+    it('returns an empty object when callers omit every meaningful signal', () => {
+        expect(sanitizeStartupResolutionSignals({
+            taskText: '',
+            explicitScope: ' ',
+            changedPaths: [''],
+            reviewedArtifactRefs: [],
+            branchName: undefined,
+            worktreeName: null,
+            sourceSurface: 'graphql',
+        })).toEqual({});
+    });
+    it('handles the shared behavioral sanitizer cases identically to the Convex copy (path + surface drift guard)', () => {
+        const cases = loadSanitizerCases();
+        for (const c of cases.paths) {
+            const sanitized = sanitizeStartupResolutionSignals({ changedPaths: [c.input] });
+            if (c.accepted) {
+                expect(sanitized.changedPaths, `path "${c.input}" should be accepted`).toEqual([c.normalized]);
+            }
+            else {
+                expect(sanitized.changedPaths, `path "${c.input}" should be rejected`).toBeUndefined();
+            }
+        }
+        for (const c of cases.sourceSurfaces) {
+            const sanitized = sanitizeStartupResolutionSignals({ sourceSurface: c.input });
+            if (c.accepted) {
+                expect(sanitized.sourceSurface, `surface "${c.input}" should be accepted`).toBe(c.normalized);
+            }
+            else {
+                expect(sanitized.sourceSurface, `surface "${c.input}" should be rejected`).toBeUndefined();
+            }
+        }
+    });
+    it('can sanitize the shared Slice 1 resolver fixtures without importing outside the CLI rootDir', () => {
+        const fixtures = loadResolutionFixtures();
+        expect(Object.keys(fixtures)).toEqual([
+            'reviewTask',
+            'prRef',
+            'entryRef',
+            'workPackageRef',
+            'changedPath',
+            'lowConfidenceUnresolved',
+            'explicitScopeOverride',
+        ]);
+        for (const fixture of Object.values(fixtures)) {
+            expect(sanitizeStartupResolutionSignals(fixture)).not.toEqual({});
+        }
+        expect(fixtures.lowConfidenceUnresolved.expectedRetrievalState).toBe('domain-unresolved');
+        expect(fixtures.explicitScopeOverride.expectedResolutionPreference).toBe('explicit-scope');
+    });
+});
+//# sourceMappingURL=startup-resolution-signals.test.js.map

package/dist/lib/startup-resolution-signals.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-resolution-signals.test.js","sourceRoot":"","sources":["../../src/lib/startup-resolution-signals.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * CLI setup state resolution — determines where the user is in the setup journey
+ * and what render tier to use for output.
+ *
+ * WP-325 S1: Foundation utilities consumed by S2 (index.ts) and S3 (connect.ts).
+ * No callers wired in this slice — this is the shared substrate.
+ *
+ * Stage model:
+ *   unconfigured     → no API key found anywhere
+ *   authenticated    → API key present, but workspace unreachable (offline or not yet connected)
+ *   workspace-bound  → key + workspace reachable, but no active session
+ *   active           → key + workspace + active session
+ */
+/** Four-stage setup journey from cold start to active use. */
+export type SetupStage = 'unconfigured' | 'authenticated' | 'workspace-bound' | 'active';
+export interface SetupState {
+    stage: SetupStage;
+    /** Human-readable list of what is still missing. Empty when stage === 'active'. */
+    missingSteps: string[];
+    /** Single most important next command to run. */
+    nextAction: string;
+    /** Workspace name — populated when workspace probe succeeds. */
+    workspaceName?: string;
+    /** Total entry count from the workspace — populated when workspace probe succeeds. */
+    entryCount?: number;
+    /** Whether a write session is currently active. */
+    sessionActive?: boolean;
+}
+/** Output render tier for the current runtime context. */
+export type RenderTier = 'json' | 'plain' | 'ink';
+/**
+ * Determine the user's current setup stage and surface what's missing.
+ *
+ * Resolution order mirrors the config cascade (getConfigSafe → probeWorkspace → readSession).
+ * Each step is attempted only if the previous one succeeded, matching how the system
+ * actually behaves when a command runs.
+ *
+ * Network calls: probeWorkspace() makes one lightweight orient call. If the caller is in a
+ * context where network is unavailable, this returns 'authenticated' rather than throwing.
+ */
+export declare function resolveSetupState(): Promise<SetupState>;
+/**
+ * Determine the appropriate output rendering tier for the current process context.
+ *
+ * Priority:
+ *   json  → isJsonMode() is true (explicit --json flag or non-TTY piped output)
+ *   plain → stdout is not a TTY (but isJsonMode() was false — e.g. --pretty on a pipe)
+ *   ink   → interactive TTY, Ink React rendering is safe
+ */
+export declare function detectRenderTier(): RenderTier;
+//# sourceMappingURL=state.d.ts.map

package/dist/lib/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/lib/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,8DAA8D;AAC9D,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,eAAe,GAAG,iBAAiB,GAAG,QAAQ,CAAC;AAEzF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,UAAU,CAAC;IAClB,mFAAmF;IACnF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAMlD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,UAAU,CAAC,CA2C7D;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAI7C"}

package/dist/lib/state.js

@@ -0,0 +1,90 @@
+/**
+ * CLI setup state resolution — determines where the user is in the setup journey
+ * and what render tier to use for output.
+ *
+ * WP-325 S1: Foundation utilities consumed by S2 (index.ts) and S3 (connect.ts).
+ * No callers wired in this slice — this is the shared substrate.
+ *
+ * Stage model:
+ *   unconfigured     → no API key found anywhere
+ *   authenticated    → API key present, but workspace unreachable (offline or not yet connected)
+ *   workspace-bound  → key + workspace reachable, but no active session
+ *   active           → key + workspace + active session
+ */
+import { getConfigSafe } from './config.js';
+import { probeWorkspace } from './workspace-probe.js';
+import { readSession } from './session.js';
+import { isJsonMode } from './runner.js';
+// ---------------------------------------------------------------------------
+// resolveSetupState
+// ---------------------------------------------------------------------------
+/**
+ * Determine the user's current setup stage and surface what's missing.
+ *
+ * Resolution order mirrors the config cascade (getConfigSafe → probeWorkspace → readSession).
+ * Each step is attempted only if the previous one succeeded, matching how the system
+ * actually behaves when a command runs.
+ *
+ * Network calls: probeWorkspace() makes one lightweight orient call. If the caller is in a
+ * context where network is unavailable, this returns 'authenticated' rather than throwing.
+ */
+export async function resolveSetupState() {
+    // Step 1 — is an API key configured?
+    const configResult = getConfigSafe();
+    if (!configResult.ok) {
+        return {
+            stage: 'unconfigured',
+            missingSteps: ['API key not found'],
+            nextAction: 'pb login',
+        };
+    }
+    // Step 2 — can we reach the workspace?
+    const wsInfo = await probeWorkspace();
+    if (!wsInfo) {
+        return {
+            stage: 'authenticated',
+            missingSteps: ['Workspace not connected or unreachable'],
+            nextAction: 'pb connect',
+        };
+    }
+    // Step 3 — is there an active write session?
+    const session = readSession();
+    if (!session) {
+        return {
+            stage: 'workspace-bound',
+            missingSteps: ['No active write session'],
+            nextAction: 'pb session start',
+            workspaceName: wsInfo.name,
+            entryCount: wsInfo.entryCount,
+            sessionActive: false,
+        };
+    }
+    // All steps satisfied — fully active
+    return {
+        stage: 'active',
+        missingSteps: [],
+        nextAction: 'pb orient -b',
+        workspaceName: wsInfo.name,
+        entryCount: wsInfo.entryCount,
+        sessionActive: true,
+    };
+}
+// ---------------------------------------------------------------------------
+// detectRenderTier
+// ---------------------------------------------------------------------------
+/**
+ * Determine the appropriate output rendering tier for the current process context.
+ *
+ * Priority:
+ *   json  → isJsonMode() is true (explicit --json flag or non-TTY piped output)
+ *   plain → stdout is not a TTY (but isJsonMode() was false — e.g. --pretty on a pipe)
+ *   ink   → interactive TTY, Ink React rendering is safe
+ */
+export function detectRenderTier() {
+    if (isJsonMode())
+        return 'json';
+    if (!process.stdout.isTTY)
+        return 'plain';
+    return 'ink';
+}
+//# sourceMappingURL=state.js.map

package/dist/lib/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/lib/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA0BzC,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,qCAAqC;IACrC,MAAM,YAAY,GAAG,aAAa,EAAE,CAAC;IACrC,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;QACrB,OAAO;YACL,KAAK,EAAE,cAAc;YACrB,YAAY,EAAE,CAAC,mBAAmB,CAAC;YACnC,UAAU,EAAE,UAAU;SACvB,CAAC;IACJ,CAAC;IAED,uCAAuC;IACvC,MAAM,MAAM,GAAG,MAAM,cAAc,EAAE,CAAC;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,KAAK,EAAE,eAAe;YACtB,YAAY,EAAE,CAAC,wCAAwC,CAAC;YACxD,UAAU,EAAE,YAAY;SACzB,CAAC;IACJ,CAAC;IAED,6CAA6C;IAC7C,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,KAAK,EAAE,iBAAiB;YACxB,YAAY,EAAE,CAAC,yBAAyB,CAAC;YACzC,UAAU,EAAE,kBAAkB;YAC9B,aAAa,EAAE,MAAM,CAAC,IAAI;YAC1B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,aAAa,EAAE,KAAK;SACrB,CAAC;IACJ,CAAC;IAED,qCAAqC;IACrC,OAAO;QACL,KAAK,EAAE,QAAQ;QACf,YAAY,EAAE,EAAE;QAChB,UAAU,EAAE,cAAc;QAC1B,aAAa,EAAE,MAAM,CAAC,IAAI;QAC1B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,aAAa,EAAE,IAAI;KACpB,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,UAAU,EAAE;QAAE,OAAO,MAAM,CAAC;IAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IAC1C,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/lib/strip.d.ts

@@ -7,5 +7,6 @@
  *
  * Chain: DEC-299 (JSON-default output), TEN-340 (Convex internal exposure)
  */
+export declare function stripControlChars(str: string): string;
 export declare function stripConvexInternals<T>(data: T): T;
 //# sourceMappingURL=strip.d.ts.map

package/dist/lib/strip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strip.d.ts","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAelD"}
+{"version":3,"file":"strip.d.ts","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAelD"}

package/dist/lib/strip.js

@@ -8,6 +8,21 @@
  * Chain: DEC-299 (JSON-default output), TEN-340 (Convex internal exposure)
  */
 const STRIP_KEYS = new Set(['_id', '_creationTime']);
+/**
+ * Strip ANSI escape sequences and control characters from user-controlled strings
+ * before printing to the terminal. Prevents terminal injection attacks where
+ * entry names/descriptions could contain escape sequences that manipulate
+ * terminal state (cursor movement, color overrides, title changes, etc.).
+ *
+ * BET-269: Security baseline — C3 (CLI terminal escaping).
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_AND_CONTROL_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]|\x1b\[[0-9;]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b[^[\]0-9;A-Za-z]?/g;
+export function stripControlChars(str) {
+    if (!str)
+        return str;
+    return str.replace(ANSI_AND_CONTROL_RE, '');
+}
 export function stripConvexInternals(data) {
     if (Array.isArray(data)) {
         return data.map((item) => stripConvexInternals(item));

package/dist/lib/strip.js.map

@@ -1 +1 @@
-{"version":3,"file":"strip.js","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;AAErD,MAAM,UAAU,oBAAoB,CAAI,IAAO;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAiB,CAAC;IACxE,CAAC;IAED,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YAC3E,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAClC,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAsB,CAAC;IAChC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"strip.js","sourceRoot":"","sources":["../../src/lib/strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;AAErD;;;;;;;GAOG;AACH,4CAA4C;AAC5C,MAAM,mBAAmB,GAAG,kGAAkG,CAAC;AAE/H,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,OAAO,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAI,IAAO;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAiB,CAAC;IACxE,CAAC;IAED,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YAC3E,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAClC,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,MAAsB,CAAC;IAChC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}