From 0a8979a46b58aa948a3eff21a46c1d07173183ec Mon Sep 17 00:00:00 2001 From: rickylabs <129366361+rickylabs@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:28:41 +0100 Subject: [PATCH 1/5] fix(kv): reject unconfirmed Redis EXEC command results Validate complete command receipts before success or watch notifications. Keep partial or unknown outcomes separate from CAS conflicts and preserve the original failure across cleanup. Closes #2648 --- packages/kv/README.md | 94 ++++---- packages/kv/adapters/redis.adapter.ts | 28 ++- packages/kv/adapters/redis/atomic-result.ts | 27 +++ packages/kv/application/errors.ts | 27 +++ packages/kv/mod.ts | 8 +- .../kv/tests/redis-atomic-outcomes_test.ts | 204 ++++++++++++++++++ packages/kv/types/common.ts | 7 +- 7 files changed, 348 insertions(+), 47 deletions(-) create mode 100644 packages/kv/adapters/redis/atomic-result.ts create mode 100644 packages/kv/tests/redis-atomic-outcomes_test.ts diff --git a/packages/kv/README.md b/packages/kv/README.md index 0480e8b08d..1cefbfeee3 100644 --- a/packages/kv/README.md +++ b/packages/kv/README.md @@ -19,6 +19,24 @@ The watch capability is the differentiator: `watch` and `watchPrefix` turn the s source, streaming typed change events as keys are written — the primitive NetScript's own reactive features build on. +## Redis atomic confirmation and recovery + +`atomic()` confirms every queued command before returning `ok: true` or publishing watch changes. A +null Redis `EXEC` response is an optimistic conflict and retains bounded conflict retries. A failed +version check returns `ok: false` without executing mutations. + +Redis can apply other commands in a transaction even when one command fails. A rejected EXEC, +command error, or malformed receipt throws `KvAtomicCommitUnconfirmedError`, exported from +`@netscript/kv`. Its payload-free `reason` is `command_failed`, `malformed_result`, or +`execution_unconfirmed`, and `possiblyApplied` is true. This is not a rollback or harmless +contention result. Reconcile expected versions and durable identities before retrying, especially +for non-idempotent mutations. Applications that advance source cursors need discoverable recovery +intent before the mutation batch, since an intent written only inside that batch can also fail. + +An `ok: true` result confirms data mutation, not receipt of watch notifications. A later watch +publication failure does not undo or automatically replay committed data. Work that requires durable +delivery must use its delivery receipts and reconciliation separately from watch hints. + ## Why teams use it - **One contract, interchangeable backends** — `KvStore` and `WatchableKv` give every adapter the @@ -83,34 +101,34 @@ for await (const events of kv.watch([['users', 'alice']])) { ## Ordered listing and cursor pages -`list({ prefix, start, end, limit, reverse })` returns descendants of `prefix` in global key -order. The prefix key itself is excluded. `start` is an exclusive lower bound and `end` an -exclusive upper bound in either direction; `limit` counts entries after filtering. Advance a -forward cursor with `start: lastEntry.key`; advance a reverse cursor with `end: lastEntry.key`. -The kvdex bridge presents native Deno selectors, whose `start` is inclusive. It translates that -boundary explicitly while direct `KvStore.list` calls retain the exclusive contract above. - -Redis has no maintained ordering index. Each output window scans the whole Redis database -(including keys outside the selected namespace/prefix) and keeps -only the next K distinct matching key names in a heap, then fetches those values with `MGET`. -K is at most `REDIS_MGET_BATCH_SIZE` (default 500), or the remaining limit if smaller. A page of -up to K live entries usually needs one full SCAN cycle, even with `limit: 1`. Missing/expired or -malformed values do not consume the limit; listing advances past examined keys and refills. - -Retained candidate memory is O(K), plus one SCAN reply and one MGET reply. Redis SCAN's COUNT -is a work hint, so it does not strictly bound an individual server reply. For N scanned names, -selection costs O(N log K) per window. Larger or unlimited lists rescan for successive windows, -trading O(N × ceil(examined candidates / K) × log K) work for memory independent of prefix size. -This avoids adding an index that would need backfill and changes to writes, expiry, and atomic -transactions. Prefix watch discovery uses a private unordered single-pass scan instead, preserving -one SCAN cycle per baseline or poll. Neither listing nor watches promise snapshot isolation across -concurrent writes. +`list({ prefix, start, end, limit, reverse })` returns descendants of `prefix` in global key order. +The prefix key itself is excluded. `start` is an exclusive lower bound and `end` an exclusive upper +bound in either direction; `limit` counts entries after filtering. Advance a forward cursor with +`start: lastEntry.key`; advance a reverse cursor with `end: lastEntry.key`. The kvdex bridge +presents native Deno selectors, whose `start` is inclusive. It translates that boundary explicitly +while direct `KvStore.list` calls retain the exclusive contract above. + +Redis has no maintained ordering index. Each output window scans the whole Redis database (including +keys outside the selected namespace/prefix) and keeps only the next K distinct matching key names in +a heap, then fetches those values with `MGET`. K is at most `REDIS_MGET_BATCH_SIZE` (default 500), +or the remaining limit if smaller. A page of up to K live entries usually needs one full SCAN cycle, +even with `limit: 1`. Missing/expired or malformed values do not consume the limit; listing advances +past examined keys and refills. + +Retained candidate memory is O(K), plus one SCAN reply and one MGET reply. Redis SCAN's COUNT is a +work hint, so it does not strictly bound an individual server reply. For N scanned names, selection +costs O(N log K) per window. Larger or unlimited lists rescan for successive windows, trading O(N × +ceil(examined candidates / K) × log K) work for memory independent of prefix size. This avoids +adding an index that would need backfill and changes to writes, expiry, and atomic transactions. +Prefix watch discovery uses a private unordered single-pass scan instead, preserving one SCAN cycle +per baseline or poll. Neither listing nor watches promise snapshot isolation across concurrent +writes. Existing storage-key encoding limitations remain: Redis colon-separated keys coerce all-digit -segments to numbers and do not preserve arbitrary key-part types. Memory compares parts as -strings, while native Deno KV has typed ordering. The shared pagination contract tests use -round-trippable, non-numeric ASCII string parts (for example `k0001`); they do not establish -universal typed-key parity. +segments to numbers and do not preserve arbitrary key-part types. Memory compares parts as strings, +while native Deno KV has typed ordering. The shared pagination contract tests use round-trippable, +non-numeric ASCII string parts (for example `k0001`); they do not establish universal typed-key +parity. ## Startup consistency @@ -168,18 +186,18 @@ cleanly, while an actual adapter failure still rejects iteration. Fixed-key Redis watches restore live subscriptions after a lost connection, including when the driver has exhausted its native reconnect attempts. After Redis acknowledges each restored -subscription, the watch rereads its keys and emits current state. Missing keys appear as -`delete` events with null values. Recovery batches have no `initial` marker and may repeat -unchanged values. Intermediate mutations during an outage can coalesce: this is a current-state -watch, not a durable event log. No idle keyspace scan is added to fixed-key watches. - -Recovery has a 30-second total budget from disconnect, including connection attempts, -subscription acknowledgements and state rereads. A watch that cannot recover rejects iteration -with `KvConnectionError`, preserving the cause. Import `KvError`, `KvConnectionError` or -`KvClosedError` from `@netscript/kv` or `@netscript/kv/redis` to catch them. Closing an adapter -rejects its active watches with `KvClosedError`; aborting a watch's own signal completes it -normally. Releasing one watch preserves its siblings, and releasing the last watch cancels its -pending recovery. A new watch can start a fresh recovery after failed watches have ended. +subscription, the watch rereads its keys and emits current state. Missing keys appear as `delete` +events with null values. Recovery batches have no `initial` marker and may repeat unchanged values. +Intermediate mutations during an outage can coalesce: this is a current-state watch, not a durable +event log. No idle keyspace scan is added to fixed-key watches. + +Recovery has a 30-second total budget from disconnect, including connection attempts, subscription +acknowledgements and state rereads. A watch that cannot recover rejects iteration with +`KvConnectionError`, preserving the cause. Import `KvError`, `KvConnectionError` or `KvClosedError` +from `@netscript/kv` or `@netscript/kv/redis` to catch them. Closing an adapter rejects its active +watches with `KvClosedError`; aborting a watch's own signal completes it normally. Releasing one +watch preserves its siblings, and releasing the last watch cancels its pending recovery. A new watch +can start a fresh recovery after failed watches have ended. Prefix watches share subscription restoration and typed failure/close handling. Their existing `pollInterval` still controls discovery of keys changed without a delivered publication. diff --git a/packages/kv/adapters/redis.adapter.ts b/packages/kv/adapters/redis.adapter.ts index cc4eeebbec..e80b18943a 100644 --- a/packages/kv/adapters/redis.adapter.ts +++ b/packages/kv/adapters/redis.adapter.ts @@ -15,7 +15,11 @@ */ import { createWatchHandle } from '../application/watch-handle.ts'; -import { KvConnectionError, KvError } from '../application/errors.ts'; +import { + KvAtomicCommitUnconfirmedError, + KvConnectionError, + KvError, +} from '../application/errors.ts'; import { createPackageLogger } from '@netscript/logger'; import { combineAtomicValue } from '../application/atomic-combine.ts'; import { generateVersionstamp, keyHasPrefix, keyToString } from '../application/keys.ts'; @@ -41,6 +45,7 @@ import { type WatchMessage, } from './redis/codec.ts'; import { RedisConnectionManager } from './redis/connection.ts'; +import { assertRedisAtomicResult } from './redis/atomic-result.ts'; import { listEntries, scanEntries } from './redis/list-entries.ts'; import { keyToRedisKey } from './redis/serialization.ts'; import { WatchBatchQueue } from './redis/watch-batch-queue.ts'; @@ -353,14 +358,25 @@ export class RedisKvAdapter implements WatchableKv { const multi = client.multi(); const changes = this.queueMutations(multi, mutations, current, versionstamp); - if ((await multi.exec()) === null) { + let executed: unknown; + try { + executed = await multi.exec(); + } catch { + throw new KvAtomicCommitUnconfirmedError('execution_unconfirmed'); + } + if (executed === null) { return 'conflict'; } + assertRedisAtomicResult(executed, mutations.length); await this.publishChanges(changes, versionstamp); return { ok: true, versionstamp }; } catch (error: unknown) { - await client.unwatch(); + try { + await client.unwatch(); + } catch { + logger.warn('Redis atomic cleanup failed after an operation failure'); + } throw error; } } @@ -662,10 +678,8 @@ export class RedisKvAdapter implements WatchableKv { pipeline.publish(this.getWatchChannel(), encodeEnvelope({ ...message })); } await pipeline.exec(); - } catch (error: unknown) { - logger.warn('Failed to publish Redis KV watch event', { - error: error instanceof Error ? error.message : String(error), - }); + } catch { + logger.warn('Redis KV write committed but watch publication is unconfirmed'); } } diff --git a/packages/kv/adapters/redis/atomic-result.ts b/packages/kv/adapters/redis/atomic-result.ts new file mode 100644 index 0000000000..98c3f6ad1e --- /dev/null +++ b/packages/kv/adapters/redis/atomic-result.ts @@ -0,0 +1,27 @@ +/** Validate the complete Redis EXEC receipt before certifying a commit. */ +import { KvAtomicCommitUnconfirmedError } from '../../application/errors.ts'; + +/** + * Require one successful command tuple for every queued mutation. + * + * Null EXEC is handled by the caller as an optimistic conflict. A null detail + * inside a successful tuple is valid; only its explicit null error slot proves + * command success. A command failure can leave other mutations applied. + * + * @param result - Non-null result returned by the transport. + * @param commands - Exact number of queued Redis commands. + * @throws {KvAtomicCommitUnconfirmedError} On missing or failed confirmation. + */ +export function assertRedisAtomicResult(result: unknown, commands: number): void { + if (!Array.isArray(result) || result.length !== commands) { + throw new KvAtomicCommitUnconfirmedError('malformed_result'); + } + for (const command of result) { + if (!Array.isArray(command) || command.length !== 2 || command[0] === undefined) { + throw new KvAtomicCommitUnconfirmedError('malformed_result'); + } + if (command[0] !== null) { + throw new KvAtomicCommitUnconfirmedError('command_failed'); + } + } +} diff --git a/packages/kv/application/errors.ts b/packages/kv/application/errors.ts index 5e5ffacb71..28d21420fb 100644 --- a/packages/kv/application/errors.ts +++ b/packages/kv/application/errors.ts @@ -23,3 +23,30 @@ export class KvConnectionError extends KvError {} /** An operation or active watch failed because its adapter was closed. */ export class KvClosedError extends KvError {} + +/** Why a Redis transaction cannot be confirmed after EXEC was attempted. */ +export type KvAtomicCommitUnconfirmedReason = + | 'command_failed' + | 'malformed_result' + | 'execution_unconfirmed'; + +/** + * An attempted transaction may have applied only some mutations. + * + * This is not a failed version check. Do not retry non-idempotent mutations + * without reconciling durable state. Command payloads and original errors are + * deliberately excluded from this public failure. + */ +export class KvAtomicCommitUnconfirmedError extends KvError { + /** Some or all mutations may already be durable. */ + readonly possiblyApplied = true; + + /** + * Create a payload-free transaction uncertainty failure. + * + * @param reason - Safe classification of the missing confirmation. + */ + constructor(readonly reason: KvAtomicCommitUnconfirmedReason) { + super('KV atomic commit is unconfirmed; mutations may have applied.'); + } +} diff --git a/packages/kv/mod.ts b/packages/kv/mod.ts index 2c0426754d..707e9e1ce1 100644 --- a/packages/kv/mod.ts +++ b/packages/kv/mod.ts @@ -40,7 +40,13 @@ export type { export { isWatchable } from './types/mod.ts'; -export { KvClosedError, KvConnectionError, KvError } from './application/errors.ts'; +export { + KvAtomicCommitUnconfirmedError, + type KvAtomicCommitUnconfirmedReason, + KvClosedError, + KvConnectionError, + KvError, +} from './application/errors.ts'; export { DenoKvAdapter } from './adapters/deno-kv.adapter.ts'; export { MemoryKvAdapter } from './adapters/memory.adapter.ts'; diff --git a/packages/kv/tests/redis-atomic-outcomes_test.ts b/packages/kv/tests/redis-atomic-outcomes_test.ts new file mode 100644 index 0000000000..c0127078b0 --- /dev/null +++ b/packages/kv/tests/redis-atomic-outcomes_test.ts @@ -0,0 +1,204 @@ +/** Owning Redis adapter tests; the command transport is inert before any operation. */ +import { assert, assertEquals, assertRejects } from '@std/assert'; +import { RedisKvAdapter } from '../redis.ts'; +import type { AtomicMutation } from '../types/kv-store.ts'; + +type Reply = (commands: number, attempt: number) => unknown; +function fixture( + reply: Reply, + options: { cleanupFails?: boolean; publicationFails?: boolean } = {}, +) { + let attempts = 0; + let notifications = 0; + let unwatches = 0; + let closed = false; + const client = { + watch: () => Promise.resolve('OK'), + unwatch() { + unwatches++; + return options.cleanupFails + ? Promise.reject(new Error('synthetic cleanup failure')) + : Promise.resolve('OK'); + }, + mget: (...keys: string[]) => Promise.resolve(keys.map(() => null)), + multi() { + let commands = 0; + const multi = { + set() { + commands++; + return multi; + }, + psetex() { + commands++; + return multi; + }, + del() { + commands++; + return multi; + }, + exec() { + attempts++; + return Promise.resolve().then(() => reply(commands, attempts)); + }, + }; + return multi; + }, + pipeline() { + let commands = 0; + const pipeline = { + publish() { + notifications++; + commands++; + return pipeline; + }, + exec: () => + options.publicationFails + ? Promise.reject(new Error('synthetic publication failure')) + : Promise.resolve(Array.from({ length: commands }, () => [null, 1])), + }; + return pipeline; + }, + }; + const kv = new RedisKvAdapter({ url: 'redis://fixture.invalid', namespace: 'atomic-outcomes' }); + Object.defineProperty(kv, 'connection', { + value: { + ensureClient: () => Promise.resolve(client), + close: () => { + closed = true; + return Promise.resolve(); + }, + }, + }); + return { + kv, + attempts: () => attempts, + notifications: () => notifications, + unwatches: () => unwatches, + closed: () => closed, + }; +} +const mutations: AtomicMutation[] = [ + { type: 'set', key: ['first'], value: 'synthetic value' }, + { type: 'delete', key: ['middle'] }, + { type: 'set', key: ['last'], value: 1, expireIn: 1000 }, +]; +const success: Reply = (count) => Array.from({ length: count }, () => [null, 'OK']); + +Deno.test('Redis atomic validates all successful command tuples before notifying', async () => { + const f = fixture((count) => Array.from({ length: count }, () => [null, null])); + try { + assert((await f.kv.atomic([], mutations)).ok); + assertEquals(f.attempts(), 1); + assertEquals(f.notifications(), 3); + } finally { + await f.kv.close(); + } + assert(f.closed()); +}); + +Deno.test('Redis null EXEC retries conflict and check mismatch never executes', async () => { + const f = fixture((count, attempt) => attempt === 1 ? null : success(count, attempt)); + try { + assert((await f.kv.atomic([], mutations)).ok); + assertEquals(f.attempts(), 2); + assertEquals(f.notifications(), 3); + assertEquals(await f.kv.atomic([{ key: ['absent'], versionstamp: 'expected' }], mutations), { + ok: false, + }); + assertEquals(f.attempts(), 2); + } finally { + await f.kv.close(); + } +}); + +Deno.test('Redis repeated null EXEC retains bounded conflict failure', async () => { + const f = fixture(() => null); + try { + assertEquals(await f.kv.atomic([], mutations), { ok: false }); + assertEquals(f.attempts(), 5); + assertEquals(f.notifications(), 0); + } finally { + await f.kv.close(); + } +}); + +for (const failed of [0, 1, 2]) { + Deno.test(`Redis command failure at position ${failed} is unconfirmed without retry or notification`, async () => { + const f = fixture((count) => + Array.from( + { length: count }, + (_, i) => + i === failed + ? [new Error('synthetic command payload must remain private'), null] + : [null, 'OK'], + ) + ); + try { + const error = await assertRejects(() => f.kv.atomic([], mutations)); + assert(error instanceof Error); + assertEquals(error.name, 'KvAtomicCommitUnconfirmedError'); + assertEquals(Reflect.get(error, 'reason'), 'command_failed'); + assertEquals(Reflect.get(error, 'possiblyApplied'), true); + assertEquals(Reflect.get(error, 'cause'), undefined); + assertEquals(error.message.includes('synthetic command payload'), false); + assertEquals(f.attempts(), 1); + assertEquals(f.notifications(), 0); + } finally { + await f.kv.close(); + } + }); +} + +for ( + const [label, result] of [ + ['missing', undefined], + ['nonarray', {}], + ['short', [[null, 'OK']]], + ['long', [[null, 1], [null, 1], [null, 1], [null, 1]]], + ['malformed tuple', [[null, 1], [null], [null, 1]]], + ['missing error slot', [[null, 1], [undefined, 'OK'], [null, 1]]], + ] as const +) { + Deno.test(`Redis ${label} EXEC result cannot certify a complete commit`, async () => { + const f = fixture(() => result); + try { + const error = await assertRejects(() => f.kv.atomic([], mutations)); + assert(error instanceof Error); + assertEquals(error.name, 'KvAtomicCommitUnconfirmedError'); + assertEquals(Reflect.get(error, 'reason'), 'malformed_result'); + assertEquals(f.attempts(), 1); + assertEquals(f.notifications(), 0); + } finally { + await f.kv.close(); + } + }); +} + +Deno.test('Redis rejected EXEC stays unconfirmed when unwatch cleanup also fails', async () => { + const f = fixture(() => { + throw new Error('synthetic execution rejection'); + }, { cleanupFails: true }); + try { + const error = await assertRejects(() => f.kv.atomic([], mutations)); + assert(error instanceof Error); + assertEquals(error.name, 'KvAtomicCommitUnconfirmedError'); + assertEquals(Reflect.get(error, 'reason'), 'execution_unconfirmed'); + assertEquals(f.attempts(), 1); + assertEquals(f.unwatches(), 1); + assertEquals(f.notifications(), 0); + } finally { + await f.kv.close(); + } + assert(f.closed()); +}); + +Deno.test('Redis committed data is not replayed when later notification fails', async () => { + const f = fixture(success, { publicationFails: true }); + try { + assert((await f.kv.atomic([], mutations)).ok); + assertEquals(f.attempts(), 1); + assertEquals(f.notifications(), 3); + } finally { + await f.kv.close(); + } +}); diff --git a/packages/kv/types/common.ts b/packages/kv/types/common.ts index 46b3c347bf..9bbebf4c02 100644 --- a/packages/kv/types/common.ts +++ b/packages/kv/types/common.ts @@ -139,7 +139,12 @@ export interface AtomicCheck { * Result returned from an atomic operation. */ export interface AtomicResult { - /** Whether the operation was successful */ + /** + * Whether every mutation was confirmed committed. This does not confirm + * delivery of watch notifications. Redis may instead throw a payload-free + * KvAtomicCommitUnconfirmedError when mutations may have partially applied; + * callers must reconcile rather than treating that as an ordinary false check. + */ ok: boolean; /** New versionstamp if successful */ versionstamp?: string; From 8e8b6296181bcaabe413cf99f80a88d67e4741d9 Mon Sep 17 00:00:00 2001 From: rickylabs <129366361+rickylabs@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:19:56 +0100 Subject: [PATCH 2/5] chore(validation): refresh KV exports and retain safe CLI diagnostics Regenerate the canonical export corpus for the new atomic uncertainty error. Add strict source-reader and locked documentation options, bounded exact-byte assertions, and safe diagnostics for existing E2E stop/restart invocations. Refs #2648 --- .github/workflows/e2e-cli.yml | 4 + .llm/tools/docs/assert-corpus-bytes.ts | 22 ++ .llm/tools/docs/assert-corpus-bytes_test.ts | 20 ++ .llm/tools/docs/export-corpus-doc-command.ts | 73 +++++ .../docs/export-corpus-doc-command_test.ts | 98 +++++++ .llm/tools/docs/export-corpus-git-read.ts | 133 ++++++++++ .../tools/docs/export-corpus-git-read_test.ts | 109 ++++++++ .../docs/generate-export-surface-corpus.ts | 113 ++++---- .../generate-export-surface-corpus_test.ts | 3 +- .../gates/scaffold/database-gates.ts | 15 +- .../scaffold/runtime/evidence/cleanup.ts | 152 +++++++---- .../evidence/database-generate-diagnostic.ts | 93 +++++++ .../database-generate-diagnostic_test.ts | 53 ++++ .../runtime/evidence/invocation-diagnostic.ts | 249 ++++++++++++++++++ .../evidence/invocation-diagnostic_test.ts | 207 +++++++++++++++ .../evidence/owned-invocation-diagnostic.ts | 70 +++++ .../scaffold/verify-documented-scaffold.ts | 1 + .../export-surface-corpus.generated.ts | 2 +- 18 files changed, 1299 insertions(+), 118 deletions(-) create mode 100644 .llm/tools/docs/assert-corpus-bytes.ts create mode 100644 .llm/tools/docs/assert-corpus-bytes_test.ts create mode 100644 .llm/tools/docs/export-corpus-doc-command.ts create mode 100644 .llm/tools/docs/export-corpus-doc-command_test.ts create mode 100644 .llm/tools/docs/export-corpus-git-read.ts create mode 100644 .llm/tools/docs/export-corpus-git-read_test.ts create mode 100644 packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts create mode 100644 packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts create mode 100644 packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts create mode 100644 packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts create mode 100644 packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts diff --git a/.github/workflows/e2e-cli.yml b/.github/workflows/e2e-cli.yml index 21f381d802..22f5d1565e 100644 --- a/.github/workflows/e2e-cli.yml +++ b/.github/workflows/e2e-cli.yml @@ -389,6 +389,8 @@ jobs: .llm/tmp/e2e-report-scaffold-runtime*.ndjson .llm/tmp/e2e-image-pulls.json .llm/tmp/cli-e2e/*/.netscript/e2e/listener-unreachable-receipt.json + .llm/tmp/cli-e2e/documented-scaffold/**/.netscript/e2e-cleanup-diagnostic.json + .llm/tmp/cli-e2e/*/.netscript/e2e-restart-diagnostic.json .llm/tmp/gate-receipts/scaffold-runtime/agent.aspire-mcp-smoke* include-hidden-files: true if-no-files-found: ignore @@ -507,6 +509,8 @@ jobs: .llm/tmp/e2e-report-scaffold-runtime-sqlite*.ndjson .llm/tmp/e2e-image-pulls.json .llm/tmp/cli-e2e/*/.netscript/e2e/listener-unreachable-receipt.json + .llm/tmp/cli-e2e/documented-scaffold/**/.netscript/e2e-cleanup-diagnostic.json + .llm/tmp/cli-e2e/*/.netscript/e2e-restart-diagnostic.json .llm/tmp/gate-receipts/scaffold-runtime-sqlite/agent.aspire-mcp-smoke* .llm/tmp/showcase-ai-browser/ include-hidden-files: true diff --git a/.llm/tools/docs/assert-corpus-bytes.ts b/.llm/tools/docs/assert-corpus-bytes.ts new file mode 100644 index 0000000000..93d7ab8b0e --- /dev/null +++ b/.llm/tools/docs/assert-corpus-bytes.ts @@ -0,0 +1,22 @@ +/** Exact byte comparison with bounded failure diagnostics, never an expanded corpus diff. */ +import { AssertionError } from '@std/assert'; + +async function digest(value: Uint8Array): Promise { + const copy = new Uint8Array(value.byteLength); + copy.set(value); + return [...new Uint8Array(await crypto.subtle.digest('SHA-256', copy))] + .map((byte) => byte.toString(16).padStart(2, '0')).join(''); +} + +export async function assertExactCorpusBytes( + actual: Uint8Array, + expected: Uint8Array, +): Promise { + let equal = actual.byteLength === expected.byteLength; + for (let i = 0; equal && i < actual.byteLength; i++) equal = actual[i] === expected[i]; + if (equal) return; + throw new AssertionError( + `Corpus bytes differ: length ${actual.byteLength}/${expected.byteLength}; ` + + `SHA256 ${await digest(actual)}/${await digest(expected)}`, + ); +} diff --git a/.llm/tools/docs/assert-corpus-bytes_test.ts b/.llm/tools/docs/assert-corpus-bytes_test.ts new file mode 100644 index 0000000000..306d7bc4e0 --- /dev/null +++ b/.llm/tools/docs/assert-corpus-bytes_test.ts @@ -0,0 +1,20 @@ +import { assert, AssertionError, assertRejects } from '@std/assert'; +import { assertExactCorpusBytes } from './assert-corpus-bytes.ts'; + +Deno.test('exact corpus bytes accept identical and empty payloads', async () => { + await assertExactCorpusBytes(new Uint8Array(), new Uint8Array()); + await assertExactCorpusBytes(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); +}); +Deno.test('length or same-length last-byte mismatch stays red with bounded payload-free diagnostics', async () => { + const actual = new Uint8Array(2 << 20).fill(65), expected = actual.slice(); + expected[expected.length - 1] = 66; + for (const pair of [[actual, expected], [actual, expected.subarray(1)]]) { + const error = await assertRejects( + () => assertExactCorpusBytes(pair[0], pair[1]), + AssertionError, + ); + assert(error.message.length < 256); + assert(error.message.includes('SHA256')); + assert(!error.message.includes('AAAA')); + } +}); diff --git a/.llm/tools/docs/export-corpus-doc-command.ts b/.llm/tools/docs/export-corpus-doc-command.ts new file mode 100644 index 0000000000..11a2b99516 --- /dev/null +++ b/.llm/tools/docs/export-corpus-doc-command.ts @@ -0,0 +1,73 @@ +/** Explicit static-documentation child policy; ordinary callers keep their existing loader. */ +import { isAbsolute, join, resolve } from '@std/path'; + +export interface ExportCorpusDocOptions { + readonly lockfile?: string; + readonly importHosts?: readonly string[]; + readonly cacheDir?: string; + readonly compilerFlags?: string; + readonly onChild?: (notice: { + readonly packageName: string; + readonly ordinal: number; + readonly total: number; + readonly phase: 'attempt' | 'complete'; + readonly exitCode?: number; + }) => void; +} + +/** Construct only supported Deno doc flags and a sterile strict-mode environment. */ +export function exportCorpusDocCommand( + root: string, + entrypoints: readonly string[], + options: ExportCorpusDocOptions, + ordinaryEnvironment: () => Record, +): { args: string[]; env: Record } { + const strict = options.lockfile !== undefined || options.importHosts !== undefined || + options.cacheDir !== undefined; + if (!strict) return { args: ['doc', '--json', ...entrypoints], env: ordinaryEnvironment() }; + const lockfile = options.lockfile && resolve(root, options.lockfile); + const cache = options.cacheDir && resolve(options.cacheDir); + const hosts = options.importHosts; + if ( + lockfile !== resolve(root, 'deno.lock') || !cache || !isAbsolute(options.cacheDir!) || + cache === resolve(root) || !hosts?.length || hosts.length > 16 || + new Set(hosts).size !== hosts.length + ) { + throw new Error( + 'Locked documentation requires the repository lock, explicit cache and public import hosts', + ); + } + for (const host of hosts) { + if ( + !/^[a-z0-9]+(?:[.-][a-z0-9]+)*\.[a-z]{2,}$/.test(host) || + /(?:^|\.)(?:localhost|local|internal|invalid|test)$/.test(host) + ) { + throw new Error('Documentation import host is not an explicit public hostname'); + } + } + if ( + options.compilerFlags && !/^--max-old-space-size=[1-9][0-9]{1,4}$/.test(options.compilerFlags) + ) { + throw new Error('Unsupported documentation compiler flags'); + } + const home = join(cache, 'home'); + return { + args: [ + 'doc', + '--json', + '--lock', + lockfile, + '--frozen-lockfile', + '--allow-import=' + hosts.join(','), + '--node-modules-dir=none', + ...entrypoints, + ], + env: { + DENO_DIR: cache, + HOME: home, + USERPROFILE: home, + NO_COLOR: '1', + ...(options.compilerFlags ? { DENO_V8_FLAGS: options.compilerFlags } : {}), + }, + }; +} diff --git a/.llm/tools/docs/export-corpus-doc-command_test.ts b/.llm/tools/docs/export-corpus-doc-command_test.ts new file mode 100644 index 0000000000..3566688df6 --- /dev/null +++ b/.llm/tools/docs/export-corpus-doc-command_test.ts @@ -0,0 +1,98 @@ +import { assertEquals, assertThrows } from '@std/assert'; +import { exportCorpusDocCommand } from './export-corpus-doc-command.ts'; +import { parseExportCorpusOptions } from './export-corpus-git-read.ts'; + +const options = { + lockfile: '/synthetic/repository/deno.lock', + cacheDir: '/synthetic/cache', + importHosts: ['jsr.io', 'registry.npmjs.org'], + compilerFlags: '--max-old-space-size=1152', +}; +Deno.test('locked documentation composes supported exact child flags and never copies caller auth environment', () => { + let environmentReads = 0; + const neverRead = () => { + environmentReads++; + return { SYNTHETIC_AUTH_TOKEN: 'never-copy-fixture' }; + }; + const plan = exportCorpusDocCommand( + '/synthetic/repository', + ['first.ts', 'second.ts'], + options, + neverRead, + ); + assertEquals(plan.args, [ + 'doc', + '--json', + '--lock', + options.lockfile, + '--frozen-lockfile', + '--allow-import=jsr.io,registry.npmjs.org', + '--node-modules-dir=none', + 'first.ts', + 'second.ts', + ]); + assertEquals(plan.env, { + DENO_DIR: '/synthetic/cache', + HOME: '/synthetic/cache/home', + USERPROFILE: '/synthetic/cache/home', + NO_COLOR: '1', + DENO_V8_FLAGS: '--max-old-space-size=1152', + }); + assertEquals( + Object.keys(plan.env).some((key) => /token|auth|proxy|session|force_color/i.test(key)), + false, + ); + assertEquals(plan.args.includes('--cached-only'), false); + assertEquals(environmentReads, 0); +}); +Deno.test('strict documentation refuses incomplete locks, private hosts, cache overrides and arbitrary compiler flags', () => { + const ordinary = () => ({}); + for ( + const invalid of [ + { ...options, lockfile: '/elsewhere/deno.lock' }, + { ...options, cacheDir: '/synthetic/repository' }, + { ...options, cacheDir: 'relative-cache' }, + { ...options, importHosts: ['localhost'] }, + { ...options, importHosts: ['service.internal'] }, + { ...options, importHosts: ['127.0.0.1'] }, + { ...options, importHosts: ['https://jsr.io'] }, + { ...options, importHosts: ['jsr.io', 'jsr.io'] }, + { ...options, compilerFlags: '--allow-natives-syntax' }, + { cacheDir: '/synthetic/cache' }, + { lockfile: options.lockfile }, + ] + ) { + assertThrows(() => + exportCorpusDocCommand('/synthetic/repository', ['first.ts'], invalid, ordinary) + ); + } +}); +Deno.test('ordinary documentation command and colour-normalized environment remain unchanged', () => { + const env = { NO_COLOR: '1', EXAMPLE: 'unchanged' }; + assertEquals(exportCorpusDocCommand('/synthetic/repository', ['first.ts'], {}, () => env), { + args: ['doc', '--json', 'first.ts'], + env, + }); +}); +Deno.test('documented strict CLI flags map to typed policy without accepting unsupported native cached-only', () => { + assertEquals( + parseExportCorpusOptions([ + '--doc-lockfile', + options.lockfile, + '--doc-cache-dir', + options.cacheDir, + '--doc-import-hosts', + 'jsr.io,registry.npmjs.org', + ]), + { + check: false, + allowDirty: false, + gitReadWrapper: undefined, + docLockfile: options.lockfile, + docCacheDir: options.cacheDir, + docImportHosts: options.importHosts, + }, + ); + assertThrows(() => parseExportCorpusOptions(['--cached-only'])); + assertThrows(() => parseExportCorpusOptions(['--doc-lockfile'])); +}); diff --git a/.llm/tools/docs/export-corpus-git-read.ts b/.llm/tools/docs/export-corpus-git-read.ts new file mode 100644 index 0000000000..148d094187 --- /dev/null +++ b/.llm/tools/docs/export-corpus-git-read.ts @@ -0,0 +1,133 @@ +/** Explicit Git-read delegation for the generator's existing clean-source guard. */ +import { resolve } from '@std/path'; + +export interface GeneratorGitCommand { + readonly executable: string; + readonly args: string[]; + readonly cwd: string; + readonly strict: boolean; +} +export interface GeneratorGitOutput { + readonly success: boolean; + readonly code: number; + readonly stdout: Uint8Array; + readonly stderr: Uint8Array; +} +export type GeneratorGitExecutor = (command: GeneratorGitCommand) => Promise; + +/** Parse supported generator options without treating wrapper values as new flags. */ +export function parseExportCorpusOptions(args: readonly string[]): { + check: boolean; + allowDirty: boolean; + gitReadWrapper?: string; + docLockfile?: string; + docCacheDir?: string; + docImportHosts?: string[]; +} { + const check = args.includes('--check'), allowDirty = args.includes('--allow-dirty'); + const index = args.indexOf('--git-read-wrapper'); + const gitReadWrapper = index < 0 ? undefined : args[index + 1]; + if ( + index >= 0 && (!gitReadWrapper || gitReadWrapper.startsWith('--') || + args.lastIndexOf('--git-read-wrapper') !== index) + ) throw new Error('--git-read-wrapper requires one executable'); + const docFlags = ['--doc-lockfile', '--doc-cache-dir', '--doc-import-hosts']; + const docValues: (string | undefined)[] = []; + const consumed = new Set(); + for (const flag of docFlags) { + const at = args.indexOf(flag), value = at < 0 ? undefined : args[at + 1]; + if (at >= 0) { + if (!value || value.startsWith('--') || args.lastIndexOf(flag) !== at) { + throw new Error(`${flag} requires one value`); + } + consumed.add(at); + consumed.add(at + 1); + } + docValues.push(value); + } + const unknown = args.filter((value, position) => + !consumed.has(position) && + value !== '--check' && value !== '--allow-dirty' && + !(index >= 0 && (position === index || position === index + 1)) + ); + if (unknown.length) throw new Error(`unknown argument: ${unknown[0]}`); + if (check && allowDirty) { + throw new Error('--allow-dirty is only valid when writing the generated corpus'); + } + if (gitReadWrapper && allowDirty) throw new Error('--git-read-wrapper cannot use --allow-dirty'); + return { + check, + allowDirty, + gitReadWrapper, + ...(docValues[0] !== undefined ? { docLockfile: docValues[0] } : {}), + ...(docValues[1] !== undefined ? { docCacheDir: docValues[1] } : {}), + ...(docValues[2] !== undefined ? { docImportHosts: docValues[2].split(',') } : {}), + }; +} + +/** The wrapper receives the actual resolved workspace and the exact source read set. */ +export function generatorGitCommand(root: string, wrapper?: string): GeneratorGitCommand { + const cwd = resolve(root); + const args = ['status', '--porcelain', '--', 'packages', 'plugins']; + return wrapper + ? { executable: wrapper, args: [cwd, '--', ...args], cwd, strict: true } + : { executable: 'git', args, cwd, strict: false }; +} + +async function execute(command: GeneratorGitCommand): Promise { + return await new Deno.Command(command.executable, { + args: command.args, + cwd: command.cwd, + stdout: 'piped', + stderr: 'piped', + ...(command.strict ? { signal: AbortSignal.timeout(20_000) } : {}), + }).output(); +} + +/** + * Preserve the ordinary generator guard; explicit delegation refuses closed. + * A wrapper failure never falls back to Git or a separate earlier clean proof. + */ +export async function guardGeneratorWrite( + root: string, + options: { readonly allowDirty: boolean; readonly gitReadWrapper?: string }, + run: GeneratorGitExecutor = execute, +): Promise { + if (options.gitReadWrapper && options.allowDirty) { + throw new Error('An approved Git read wrapper cannot be combined with --allow-dirty'); + } + const command = generatorGitCommand(root, options.gitReadWrapper); + let output: GeneratorGitOutput; + try { + output = await run(command); + } catch (error) { + if (command.strict) { + throw new Error('Approved Git read did not confirm clean generator sources'); + } + console.warn( + 'WARNING: Git is unavailable; continuing MCP export-corpus generation without ' + + `clean-tree verification (${error instanceof Error ? error.message : String(error)}).`, + ); + return; + } + if (!output.success) { + if (command.strict) throw new Error('Approved Git read refused generator source verification'); + const detail = new TextDecoder().decode(output.stderr).trim() || `exit ${output.code}`; + console.warn( + 'WARNING: Git status is unavailable; continuing MCP export-corpus generation without ' + + `clean-tree verification (${detail}).`, + ); + return; + } + const dirty = new TextDecoder().decode(output.stdout).trimEnd(); + if (!dirty) return; + const summary = `MCP export-corpus generator read set is dirty:\n${dirty}`; + if (options.allowDirty) { + console.warn(`WARNING: ${summary}\nProceeding because --allow-dirty was explicitly supplied.`); + return; + } + throw new Error( + `${summary}\nRefusing to generate from uncommitted package/plugin sources. ` + + 'Commit or stash them, or deliberately rerun with --allow-dirty.', + ); +} diff --git a/.llm/tools/docs/export-corpus-git-read_test.ts b/.llm/tools/docs/export-corpus-git-read_test.ts new file mode 100644 index 0000000000..844d880c9f --- /dev/null +++ b/.llm/tools/docs/export-corpus-git-read_test.ts @@ -0,0 +1,109 @@ +import { assertEquals, assertRejects, assertThrows } from '@std/assert'; +import { + generatorGitCommand, + guardGeneratorWrite, + parseExportCorpusOptions, +} from './export-corpus-git-read.ts'; + +const root = '/synthetic/repository'; +const wrapper = '/synthetic/tools/approved-read'; +const clean = { success: true, code: 0, stdout: new Uint8Array(), stderr: new Uint8Array() }; + +Deno.test('explicit Git delegation composes the exact resolved source guard without raw fallback', async () => { + const calls: unknown[] = []; + await guardGeneratorWrite(root, { allowDirty: false, gitReadWrapper: wrapper }, (command) => { + calls.push(command); + return Promise.resolve(clean); + }); + assertEquals(calls, [{ + executable: wrapper, + args: [root, '--', 'status', '--porcelain', '--', 'packages', 'plugins'], + cwd: root, + strict: true, + }]); + assertEquals(generatorGitCommand(root), { + executable: 'git', + args: ['status', '--porcelain', '--', 'packages', 'plugins'], + cwd: root, + strict: false, + }); +}); + +for (const reason of ['spawn refusal', 'timeout', 'permission refusal']) { + Deno.test(`approved reader ${reason} fails closed and never invokes fallback`, async () => { + let calls = 0; + await assertRejects( + () => + guardGeneratorWrite(root, { allowDirty: false, gitReadWrapper: wrapper }, () => { + calls++; + throw new Error(reason); + }), + Error, + 'Approved Git read did not confirm', + ); + assertEquals(calls, 1); + }); +} +Deno.test('approved reader nonzero is refusal rather than unverified success', async () => { + let calls = 0; + await assertRejects( + () => + guardGeneratorWrite(root, { allowDirty: false, gitReadWrapper: wrapper }, () => { + calls++; + return Promise.resolve({ ...clean, success: false, code: 2 }); + }), + Error, + 'Approved Git read refused', + ); + assertEquals(calls, 1); +}); +Deno.test('approved read preserves the committed package/plugin guard and rejects bypass', async () => { + await assertRejects( + () => + guardGeneratorWrite( + root, + { allowDirty: false, gitReadWrapper: wrapper }, + () => + Promise.resolve({ + ...clean, + stdout: new TextEncoder().encode(' M packages/example/mod.ts\n'), + }), + ), + Error, + 'read set is dirty', + ); + await assertRejects( + () => + guardGeneratorWrite( + root, + { allowDirty: true, gitReadWrapper: wrapper }, + () => Promise.resolve(clean), + ), + Error, + 'cannot be combined', + ); +}); +Deno.test('generator flags reject unknown first arguments and ambiguous wrapper/bypass combinations', () => { + assertEquals(parseExportCorpusOptions([]), { + check: false, + allowDirty: false, + gitReadWrapper: undefined, + }); + assertEquals(parseExportCorpusOptions(['--git-read-wrapper', wrapper]), { + check: false, + allowDirty: false, + gitReadWrapper: wrapper, + }); + for ( + const args of [ + ['--unknown'], + ['--git-read-wrapper'], + ['--git-read-wrapper', '--check'], + ['--git-read-wrapper', wrapper, '--git-read-wrapper', wrapper], + ['--check', '--allow-dirty'], + ['--git-read-wrapper', wrapper, '--allow-dirty'], + ] + ) { + assertThrows(() => parseExportCorpusOptions(args)); + } +}); diff --git a/.llm/tools/docs/generate-export-surface-corpus.ts b/.llm/tools/docs/generate-export-surface-corpus.ts index bc8d53dde2..2bcbb26d1a 100644 --- a/.llm/tools/docs/generate-export-surface-corpus.ts +++ b/.llm/tools/docs/generate-export-surface-corpus.ts @@ -1,10 +1,13 @@ /** Generate the version-pinned MCP export corpus from Deno's structured documentation surface. */ import { dirname, fromFileUrl, join, resolve, toFileUrl } from '@std/path'; +import { guardGeneratorWrite, parseExportCorpusOptions } from './export-corpus-git-read.ts'; +import { + exportCorpusDocCommand, + type ExportCorpusDocOptions, +} from './export-corpus-doc-command.ts'; const REPO_ROOT = resolve(dirname(fromFileUrl(import.meta.url)), '../../..'); -const ALLOW_DIRTY_ARGUMENT = '--allow-dirty'; -const GENERATOR_READ_SET = ['packages', 'plugins'] as const; /** Repository-relative generated corpus staged by release preparation. */ export const EXPORT_SURFACE_CORPUS_OUTPUT = 'packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts'; @@ -240,6 +243,7 @@ ${rows.join('\n\n')} /** Generate the complete first-party export corpus from current package export maps. */ export async function buildExportSurfaceCorpus( root: string = REPO_ROOT, + docOptions: ExportCorpusDocOptions = {}, ): Promise { const rootManifest = await readManifest(join(root, 'deno.json')); if (typeof rootManifest.version !== 'string' || !rootManifest.version.trim()) { @@ -255,17 +259,37 @@ export async function buildExportSurfaceCorpus( } const entries: GeneratedExportSurfaceEntry[] = []; - for (const packageName of [...new Set(sources.map((source) => source.packageName))].sort()) { + const packageNames = [...new Set(sources.map((source) => source.packageName))].sort(); + for (const [index, packageName] of packageNames.entries()) { const packageSources = sources.filter((source) => source.packageName === packageName); + const plan = exportCorpusDocCommand( + root, + packageSources.map((source) => source.entrypoint), + docOptions, + colorInvariantChildEnv, + ); const command = new Deno.Command(Deno.execPath(), { - args: ['doc', '--json', ...packageSources.map((source) => source.entrypoint)], + args: plan.args, cwd: root, - env: colorInvariantChildEnv(), + env: plan.env, clearEnv: true, stdout: 'piped', stderr: 'piped', }); + docOptions.onChild?.({ + packageName, + ordinal: index + 1, + total: packageNames.length, + phase: 'attempt', + }); const output = await command.output(); + docOptions.onChild?.({ + packageName, + ordinal: index + 1, + total: packageNames.length, + phase: 'complete', + exitCode: output.code, + }); if (!output.success) { throw new Error( `deno doc failed for ${packageName}: ${new TextDecoder().decode(output.stderr).trim()}`, @@ -526,48 +550,6 @@ export function colorInvariantChildEnv(): Record { return env; } -async function guardGeneratorWrite(root: string, allowDirty: boolean): Promise { - let output: Deno.CommandOutput; - try { - output = await new Deno.Command('git', { - args: ['status', '--porcelain', '--', ...GENERATOR_READ_SET], - cwd: root, - stdout: 'piped', - stderr: 'piped', - }).output(); - } catch (error) { - console.warn( - `WARNING: Git is unavailable; continuing MCP export-corpus generation without ` + - `clean-tree verification (${error instanceof Error ? error.message : String(error)}).`, - ); - return; - } - - if (!output.success) { - const detail = new TextDecoder().decode(output.stderr).trim() || `exit ${output.code}`; - console.warn( - `WARNING: Git status is unavailable; continuing MCP export-corpus generation without ` + - `clean-tree verification (${detail}).`, - ); - return; - } - - const dirty = new TextDecoder().decode(output.stdout).trimEnd(); - if (!dirty) return; - - const summary = `MCP export-corpus generator read set is dirty:\n${dirty}`; - if (allowDirty) { - console.warn( - `WARNING: ${summary}\nProceeding because ${ALLOW_DIRTY_ARGUMENT} was explicitly supplied.`, - ); - return; - } - throw new Error( - `${summary}\nRefusing to generate from uncommitted package/plugin sources. ` + - `Commit or stash them, or deliberately rerun with ${ALLOW_DIRTY_ARGUMENT}.`, - ); -} - async function formatTypeScript(source: string): Promise { const child = new Deno.Command(Deno.execPath(), { args: ['fmt', '--ext', 'ts', '-'], @@ -589,18 +571,35 @@ async function formatTypeScript(source: string): Promise { } if (import.meta.main) { - const check = Deno.args.includes('--check'); - const allowDirty = Deno.args.includes(ALLOW_DIRTY_ARGUMENT); - const unknown = Deno.args.filter((argument) => - argument !== '--check' && argument !== ALLOW_DIRTY_ARGUMENT - ); - if (unknown.length > 0) throw new Error(`unknown argument: ${unknown[0]}`); - if (check && allowDirty) { - throw new Error(`${ALLOW_DIRTY_ARGUMENT} is only valid when writing the generated corpus`); + if (Deno.args.includes('--help')) { + console.log([ + 'Generate/check the structured MCP export corpus.', + '--check Compare without writing.', + '--allow-dirty Explicit ordinary-mode bypass; incompatible with approved reader.', + '--git-read-wrapper Delegate exact committed-source status read; refusal fails closed.', + '--doc-lockfile Exact repository deno.lock for frozen public-source documentation.', + '--doc-import-hosts Comma-separated explicit public import hostnames.', + '--doc-cache-dir Dedicated absolute child cache; sterile child home/environment.', + 'Supply all three --doc-* flags together. No reload, lock write, root node_modules or app execution.', + ].join('\n')); + Deno.exit(0); } - if (!check) await guardGeneratorWrite(REPO_ROOT, allowDirty); + const { check, allowDirty, gitReadWrapper, docLockfile, docCacheDir, docImportHosts } = + parseExportCorpusOptions(Deno.args); + if (!check) await guardGeneratorWrite(REPO_ROOT, { allowDirty, gitReadWrapper }); const current = await Deno.readTextFile(OUTPUT_PATH).catch(() => ''); - const asset = await createGeneratedAsset(await buildExportSurfaceCorpus(), current); + const asset = await createGeneratedAsset( + await buildExportSurfaceCorpus(REPO_ROOT, { + lockfile: docLockfile, + cacheDir: docCacheDir, + importHosts: docImportHosts, + compilerFlags: docCacheDir ? Deno.env.get('DENO_V8_FLAGS') : undefined, + onChild: docCacheDir + ? (notice) => console.error(JSON.stringify({ docChild: notice })) + : undefined, + }), + current, + ); if (check) { if (current !== asset.source) { throw new Error('MCP export-surface corpus is stale; run deno task gen:mcp-export-corpus'); diff --git a/.llm/tools/docs/generate-export-surface-corpus_test.ts b/.llm/tools/docs/generate-export-surface-corpus_test.ts index 6124e50417..715ca04ff2 100644 --- a/.llm/tools/docs/generate-export-surface-corpus_test.ts +++ b/.llm/tools/docs/generate-export-surface-corpus_test.ts @@ -1,5 +1,6 @@ import { assert, assertEquals, assertMatch } from '@std/assert'; import { EmbeddedExportSurfaceCorpus } from '../../../packages/mcp/mod.ts'; +import { assertExactCorpusBytes } from './assert-corpus-bytes.ts'; import { colorInvariantChildEnv, createGeneratedAsset, @@ -270,7 +271,7 @@ Deno.test('write mode generates the artifact from a clean committed tree', async const generated = await runGenerator(worktree); assertEquals(generated.code, 0, generated.stderr); - assertEquals(await Deno.readFile(corpusPath(worktree)), before); + await assertExactCorpusBytes(await Deno.readFile(corpusPath(worktree)), before); await assertArtifactWasWritten(worktree, oldTime); }); }); diff --git a/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts b/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts index ed348a7754..fd4245c518 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts @@ -80,8 +80,18 @@ export function createDatabaseGates(): readonly GateDefinition[] { GATE.DATABASE_GENERATE, 'Generate database clients', GATE_PHASE.DATABASE, - (context) => - cli( + (context) => [ + 'deno', + 'run', + '--allow-all', + join( + context.project.repoRoot, + 'packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts', + ), + context.project.projectRoot, + context.project.appHost, + '--', + ...cli( context, 'db', 'generate', @@ -90,6 +100,7 @@ export function createDatabaseGates(): readonly GateDefinition[] { '--db', context.request.options.database, ), + ], ), commandGate( GATE.DATABASE_DEPLOY, diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts index aba0a5150a..c82e1652fe 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts @@ -1,4 +1,6 @@ +import { saveOwnedInvocationDiagnostics } from './owned-invocation-diagnostic.ts'; import { basename, dirname, isAbsolute, relative, resolve } from '@std/path'; +import { type CapturedInvocation, withInvocationEvidence } from './invocation-diagnostic.ts'; export const ASPIRE_MOUNTS = 'com.microsoft.developer.usvc-dev.mountsLabel'; export const ASPIRE_CREATOR_PID = 'com.microsoft.developer.usvc-dev.creatorProcessId'; @@ -182,64 +184,97 @@ export async function stopAndProbe( projectRoot: string, cleanup: boolean, receiptPath: string, + options: { + readonly run?: typeof capture; + readonly wait?: (ms: number) => Promise; + readonly diagnostic?: ( + transcripts: readonly CapturedInvocation[], + evaluation?: PostStopProbeEvaluation, + ) => Promise; + } = {}, ): Promise { - const commands: (readonly string[])[] = [ - stopCommand(appHost, false), - ...(cleanup ? [stopCommand(appHost, true)] : []), - ]; - const transcripts = []; - for (const command of commands) { - transcripts.push(await capture(command[0] ?? 'aspire', command.slice(1))); - } - const idsOutput = await requireSuccess('docker', ['ps', '-aq']); - const vanishedContainerIds = new Set(); - const initialInspection = await inspectAllContainers(); - initialInspection.vanishedContainerIds.forEach((id) => vanishedContainerIds.add(id)); - // Container teardown is asynchronous to `aspire stop`, so a first probe can observe a container - // that is already on its way out. Re-probe with one forced exact-AppHost stop between attempts, - // bounded, retaining every observation as evidence. - let observedContainers = initialInspection.containers; - const { evaluation, attempts } = await resolveOwnedSurvivors( - async () => { - const inspection = await inspectAllContainers(); - observedContainers = inspection.containers; - inspection.vanishedContainerIds.forEach((id) => vanishedContainerIds.add(id)); - return evaluatePostStopProbe( - { appHost, projectRoot, containers: observedContainers, processes: [] }, - projectRoot, - ); - }, - async () => { - const forced = stopCommand(appHost, true); - transcripts.push(await capture(forced[0] ?? 'aspire', forced.slice(1))); - commands.push(forced); - }, - (ms) => new Promise((resolve) => setTimeout(resolve, ms)), - ); - const receipt = { - appHost, - cleanup, - commands, - transcripts, - docker: { - ids: idsOutput, - containers: observedContainers, - vanishedContainerIds: [...vanishedContainerIds], - }, - survivorAttempts: attempts, - evaluation, - }; - await Deno.mkdir(dirname(receiptPath), { recursive: true }); - await Deno.writeTextFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`); - assertNoOwnedSurvivors(evaluation); - const terminalStop = transcripts.at(-1); - if (!terminalStop || terminalStop.code !== 0) { - throw new Error( - `Aspire stop did not complete: ${ - terminalStop?.stderr || terminalStop?.stdout || 'no transcript' - }`, + const run = options.run ?? capture; + const transcripts: CapturedInvocation[] = []; + let finalEvaluation: PostStopProbeEvaluation | undefined; + await withInvocationEvidence(async () => { + const commands: (readonly string[])[] = [ + stopCommand(appHost, false), + ...(cleanup ? [stopCommand(appHost, true)] : []), + ]; + for (const command of commands) { + transcripts.push(await run(command[0] ?? 'aspire', command.slice(1))); + } + const idsOutput = await requireSuccess('docker', ['ps', '-aq'], run); + const vanishedContainerIds = new Set(); + const initialInspection = await inspectAllContainers(run); + initialInspection.vanishedContainerIds.forEach((id) => vanishedContainerIds.add(id)); + // Container teardown is asynchronous to `aspire stop`, so a first probe can observe a container + // that is already on its way out. Re-probe with one forced exact-AppHost stop between attempts, + // bounded, retaining every observation as evidence. + let observedContainers = initialInspection.containers; + const { evaluation, attempts } = await resolveOwnedSurvivors( + async () => { + const inspection = await inspectAllContainers(run); + observedContainers = inspection.containers; + inspection.vanishedContainerIds.forEach((id) => vanishedContainerIds.add(id)); + return evaluatePostStopProbe( + { appHost, projectRoot, containers: observedContainers, processes: [] }, + projectRoot, + ); + }, + async () => { + const forced = stopCommand(appHost, true); + transcripts.push(await run(forced[0] ?? 'aspire', forced.slice(1))); + commands.push(forced); + }, + options.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))), ); - } + finalEvaluation = evaluation; + const receipt = { + appHost, + cleanup, + commands, + transcripts, + docker: { + ids: idsOutput, + containers: observedContainers, + vanishedContainerIds: [...vanishedContainerIds], + }, + survivorAttempts: attempts, + evaluation, + }; + await Deno.mkdir(dirname(receiptPath), { recursive: true }); + await Deno.writeTextFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`); + assertNoOwnedSurvivors(evaluation); + const terminalStop = transcripts.at(-1); + if (!terminalStop || terminalStop.code !== 0) { + throw new Error( + `Aspire stop did not complete: ${ + terminalStop?.stderr || terminalStop?.stdout || 'no transcript' + }`, + ); + } + }, async () => { + if (options.diagnostic) return await options.diagnostic(transcripts, finalEvaluation); + const home = Deno.env.get('HOME') ?? Deno.env.get('USERPROFILE'); + const uid = (await Deno.stat(projectRoot)).uid; + if (!home || uid === null) throw new Error('diagnostic_owner_unavailable'); + await saveOwnedInvocationDiagnostics({ + projectRoot, + appHost, + kind: 'cleanup', + home, + uid, + transcripts, + survivorCounts: finalEvaluation + ? { + ownedContainers: finalEvaluation.ownedContainers.length, + foreignContainers: finalEvaluation.foreignContainers.length, + unprovenContainers: finalEvaluation.unprovenContainers.length, + } + : undefined, + }); + }); } /** Inspect every container currently known to Docker, so each probe sees the present state. */ @@ -287,13 +322,16 @@ export function stopCommand(appHost: string, force: boolean): readonly string[] async function capture( command: string, args: readonly string[], -): Promise<{ readonly code: number; readonly stdout: string; readonly stderr: string }> { +): Promise { + const startedAt = new Date().toISOString(); const output = await new Deno.Command(command, { args: [...args], stdout: 'piped', stderr: 'piped', }).output(); const result = { + startedAt, + completedAt: new Date().toISOString(), code: output.code, stdout: new TextDecoder().decode(output.stdout), stderr: new TextDecoder().decode(output.stderr), diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts new file mode 100644 index 0000000000..121b6a1770 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts @@ -0,0 +1,93 @@ +/** Test-only evidence around the original database.generate command; no additional Aspire calls. */ +import { saveOwnedInvocationDiagnostics } from './owned-invocation-diagnostic.ts'; +import type { CapturedInvocation } from './invocation-diagnostic.ts'; + +/** The nested Aspire exit is reported by the CLI, distinct from the captured database CLI exit. */ +export function reportedRestartFailure(text: string, appHost: string) { + const match = + /Database client generated, but (web|api|workers|postgres|redis|garnet|streams|dashboard) restart failed \(Aspire exit ([0-9]{1,3})\)\./ + .exec(text); + if ( + !match || Number(match[2]) > 255 || + !text.includes(`Run: aspire resource ${match[1]} restart --apphost ${JSON.stringify(appHost)}`) + ) return undefined; + return { resource: match[1], exit: Number(match[2]) }; +} + +/** Capture one command and return exactly its native exit; diagnostic failure cannot replace it. */ +export async function databaseGenerateWithEvidence(input: { + readonly command: readonly string[]; + readonly appHost: string; + readonly run?: (command: readonly string[]) => Promise; + readonly emit?: (stdout: string, stderr: string) => Promise; + readonly collect: (invocation: CapturedInvocation) => Promise; +}): Promise { + const run = input.run ?? (async (command: readonly string[]) => { + const startedAt = new Date().toISOString(); + const result = await new Deno.Command(command[0], { + args: command.slice(1), + stdin: 'null', + stdout: 'piped', + stderr: 'piped', + }).output(); + return { + startedAt, + completedAt: new Date().toISOString(), + code: result.code, + stdout: new TextDecoder().decode(result.stdout), + stderr: new TextDecoder().decode(result.stderr), + }; + }); + const invocation = await run(input.command); + const emit = input.emit ?? (async (stdout, stderr) => { + await Deno.stdout.write(new TextEncoder().encode(stdout)); + await Deno.stderr.write(new TextEncoder().encode(stderr)); + }); + try { + await emit(invocation.stdout, invocation.stderr); + } finally { + try { + await input.collect({ + ...invocation, + process: 'database_cli', + reportedRestart: reportedRestartFailure( + invocation.stderr + '\n' + invocation.stdout, + input.appHost, + ), + }); + } catch { + console.warn('Owned restart diagnostic unavailable; original command outcome preserved.'); + } + } + return invocation.code; +} + +if (import.meta.main) { + const [projectRoot, appHost, separator, ...command] = Deno.args; + if ( + !projectRoot || !appHost || separator !== '--' || command[0] !== 'deno' || + !command.includes('generate') || !command.includes('--project-root') || + !command.includes(projectRoot) + ) { + throw new Error('Expected the existing generated-project database command'); + } + const code = await databaseGenerateWithEvidence({ + command, + appHost, + collect: async (invocation) => { + const home = Deno.env.get('HOME') ?? Deno.env.get('USERPROFILE'); + const uid = (await Deno.stat(projectRoot)).uid; + if (!home || uid === null) throw new Error('diagnostic_owner_unavailable'); + await Deno.mkdir(`${projectRoot}/.netscript`, { recursive: true }); + await saveOwnedInvocationDiagnostics({ + projectRoot, + appHost, + kind: 'restart', + home, + uid, + transcripts: [invocation], + }); + }, + }); + Deno.exit(code); +} diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts new file mode 100644 index 0000000000..6c6cc64757 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts @@ -0,0 +1,53 @@ +import { assertEquals } from '@std/assert'; +import { + databaseGenerateWithEvidence, + reportedRestartFailure, +} from './database-generate-diagnostic.ts'; + +Deno.test('database generate diagnostic runs exactly the original command and preserves failure', async () => { + const appHost = '/synthetic/project/aspire/apphost.mts'; + const text = + `Database client generated, but web restart failed (Aspire exit 16). summary\nRun: aspire resource web restart --apphost ${ + JSON.stringify(appHost) + }`; + let runs = 0, collects = 0; + const command = ['deno', 'run', 'cli.ts', 'db', 'generate']; + const code = await databaseGenerateWithEvidence({ + command, + appHost, + run: (args) => { + runs++; + assertEquals(args, command); + return Promise.resolve({ code: 1, stdout: 'stdout detail', stderr: text }); + }, + emit: async () => {}, + collect: (invocation) => { + collects++; + assertEquals(invocation.code, 1); + assertEquals(invocation.process, 'database_cli'); + assertEquals(invocation.reportedRestart, { resource: 'web', exit: 16 }); + return Promise.reject(new Error('SECRET_COLLECTOR')); + }, + }); + assertEquals(code, 1); + assertEquals(runs, 1); + assertEquals(collects, 1); + assertEquals(reportedRestartFailure(text, '/foreign/apphost.mts'), undefined); + assertEquals(reportedRestartFailure(text.replace('exit 16', 'exit 999'), appHost), undefined); +}); +Deno.test('database generate diagnostic preserves success and does not invent a restart outcome', async () => { + let collected = 0; + const code = await databaseGenerateWithEvidence({ + command: ['deno'], + appHost: '/synthetic/apphost.mts', + run: () => Promise.resolve({ code: 0, stdout: 'success', stderr: '' }), + emit: async () => {}, + collect: (invocation) => { + collected++; + assertEquals(invocation.reportedRestart, undefined); + return Promise.resolve(); + }, + }); + assertEquals(code, 0); + assertEquals(collected, 1); +}); diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts new file mode 100644 index 0000000000..d3588cb5b4 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts @@ -0,0 +1,249 @@ +/** Bounded allowlisted evidence from an already-executed owned Aspire invocation. No process calls. */ +import { basename, isAbsolute, relative, resolve } from '@std/path'; + +const MAX_BYTES = 256 << 10; +const CLI_LOG = /^cli_(\d{8}T\d{6})_[a-f0-9]{8,32}\.log$/i; +const APPHOST_LOG = /^cli_\d{8}T\d{9}_detach-child_[a-f0-9]{8,32}\.log$/i; +const KINDS = new Set(['container', 'volume', 'network', 'process', 'project', 'executable']); +const NAMES = new Set([ + 'web', + 'api', + 'workers', + 'postgres', + 'redis', + 'garnet', + 'streams', + 'dashboard', +]); +const ERRORS = new Set(['permission_denied', 'not_found', 'in_use', 'timeout', 'cleanup_failed']); +export interface CapturedInvocation { + readonly code: number; + readonly stdout: string; + readonly stderr: string; + readonly startedAt?: string; + readonly completedAt?: string; + readonly process?: 'aspire' | 'database_cli'; + readonly reportedRestart?: { readonly resource: string; readonly exit: number }; +} +export interface DiagnosticRecord { + readonly resourceKind: string | null; + readonly resourceName: string | null; + readonly errorCode: string | null; +} +function object(value: unknown): Record | null { + return value !== null && typeof value === 'object' && !Array.isArray(value) + ? value as Record + : null; +} +function records(text: string) { + const result: DiagnosticRecord[] = []; + let ignored = 0; + for (const line of text.split(/\r?\n/)) { + if (!line.trim()) continue; + let row: Record | null = null; + try { + row = object(JSON.parse(line)); + } catch { /* Free-form text never crosses this boundary. */ } + const properties = object(row?.Properties) ?? row; + const kind = properties?.resourceKind ?? properties?.ResourceKind; + const name = properties?.resourceName ?? properties?.ResourceName; + const error = properties?.errorCode ?? properties?.ErrorCode; + const value = { + resourceKind: typeof kind === 'string' && KINDS.has(kind) ? kind : null, + resourceName: typeof name === 'string' && NAMES.has(name) ? name : null, + errorCode: typeof error === 'string' && ERRORS.has(error) ? error : null, + }; + if (Object.values(value).some((v) => v !== null) && result.length < 16) result.push(value); + else ignored++; + } + return { records: result, ignoredLines: ignored }; +} +async function sha(bytes: Uint8Array): Promise { + const copy = new Uint8Array(bytes.length); + copy.set(bytes); + return [...new Uint8Array(await crypto.subtle.digest('SHA-256', copy))] + .map((byte) => byte.toString(16).padStart(2, '0')).join(''); +} +async function textEvidence(text: string) { + const tail = text.slice(-MAX_BYTES); + const encoded = new TextEncoder().encode(tail); + const bytes = encoded.slice(-MAX_BYTES); + const truncated = tail.length !== text.length || encoded.length !== bytes.length; + return { + totalCharacters: text.length, + readBytes: bytes.length, + truncated, + capturedSha256: await sha(bytes), + ...records(new TextDecoder().decode(bytes)), + }; +} +function logReferences(text: string): string[] { + const references = new Set(); + for ( + const match of text.slice(-MAX_BYTES).matchAll( + /(?:[A-Za-z]:[\\/]|\/)[^\s<>"']*cli_[A-Za-z0-9_-]+\.log/g, + ) + ) { + references.add(match[0]); + if (references.size === 3) break; + } + return [...references]; +} +function inside(path: string, root: string) { + const delta = relative(root, path); + return delta !== '' && !delta.startsWith('..') && !isAbsolute(delta); +} +function secondStamp(iso: string | undefined): string | null { + if (!iso || !Number.isFinite(Date.parse(iso))) return null; + return new Date(iso).toISOString().slice(0, 19).replaceAll('-', '').replaceAll(':', ''); +} + +/** The same identity check is used before and after opening a selected log. */ +export function ownedDiagnosticFile(input: { + readonly file: boolean; + readonly symlink: boolean; + readonly uid: number | null; + readonly expectedUid: number; + readonly path: string; + readonly actualPath: string; + readonly root: string; + readonly actualRoot: string; +}): boolean { + return input.file && !input.symlink && input.uid === input.expectedUid && + input.actualPath === resolve(input.path) && input.actualRoot === resolve(input.root); +} + +/** One exact reference is admitted; no directory listing, home scan or raw body persistence. */ +export async function selectedInvocationLog( + path: string, + root: string, + invocation: CapturedInvocation, + uid: number, + appHost = false, +) { + const name = basename(path), match = CLI_LOG.exec(name); + const start = secondStamp(invocation.startedAt), end = secondStamp(invocation.completedAt); + if ( + !isAbsolute(path) || !inside(resolve(path), resolve(root)) || + !(appHost ? APPHOST_LOG.test(name) : match !== null) || + (!appHost && (!start || !end || match![1] < start || match![1] > end)) + ) return { status: 'refused' as const }; + try { + const before = await Deno.lstat(path); + if ( + !ownedDiagnosticFile({ + file: before.isFile, + symlink: before.isSymlink, + uid: before.uid, + expectedUid: uid, + path, + actualPath: await Deno.realPath(path), + root, + actualRoot: await Deno.realPath(root), + }) + ) return { status: 'refused' as const }; + const file = await Deno.open(path, { read: true }); + try { + const opened = await file.stat(); + if (opened.ino !== before.ino || opened.dev !== before.dev || opened.uid !== uid) { + return { status: 'refused' as const }; + } + const size = Math.min(MAX_BYTES, opened.size), bytes = new Uint8Array(size); + await file.seek(Math.max(0, opened.size - size), Deno.SeekMode.Start); + const read = size ? await file.read(bytes) : 0; + const after = await file.stat(); + if ( + read !== size || after.ino !== before.ino || after.dev !== before.dev || + await Deno.realPath(path) !== resolve(path) + ) return { status: 'unreadable' as const }; + const text = new TextDecoder().decode(bytes); + return { + status: 'available' as const, + totalBytes: opened.size, + readBytes: size, + truncated: opened.size > size, + capturedSha256: await sha(bytes), + ...records(text), + linkedAppHost: appHost + ? [] + : logReferences(text).filter((value) => APPHOST_LOG.test(basename(value))).slice(0, 2), + }; + } finally { + file.close(); + } + } catch (error) { + return { + status: error instanceof Deno.errors.NotFound ? 'missing' as const : 'unreadable' as const, + }; + } +} + +/** Keep stdout and stderr separately; stderr summaries never erase safe stdout detail. */ +export async function invocationDiagnostic(input: { + readonly invocation: CapturedInvocation; + readonly logRoot: string; + readonly uid: number; + readonly ordinal: number; + readonly operation: 'stop' | 'restart'; + readonly targetMatches: boolean; +}) { + const { invocation } = input; + const candidates = logReferences(invocation.stdout + '\n' + invocation.stderr).filter((path) => + CLI_LOG.test(basename(path)) + ); + const log = !input.targetMatches ? { status: 'refused' as const } : candidates.length !== 1 + ? { + status: candidates.length === 0 + ? 'missing_reference' as const + : 'ambiguous_reference' as const, + } + : await selectedInvocationLog(candidates[0], input.logRoot, invocation, input.uid); + const linked = 'linkedAppHost' in log ? log.linkedAppHost : []; + const linkedLog = linked.length === 1 + ? await selectedInvocationLog(linked[0], input.logRoot, invocation, input.uid, true) + : null; + // Reference paths are consumed only for exact local reads, never serialized into the artifact. + const { linkedAppHost: _paths, ...safeLog } = 'linkedAppHost' in log + ? log + : { ...log, linkedAppHost: [] }; + const { linkedAppHost: _nested, ...safeLinked } = linkedLog && 'linkedAppHost' in linkedLog + ? linkedLog + : { ...linkedLog, linkedAppHost: [] }; + return { + ordinal: input.ordinal, + operation: input.operation, + nativeExit: invocation.code, + process: invocation.process ?? 'aspire', + reportedRestart: invocation.reportedRestart && NAMES.has(invocation.reportedRestart.resource) && + Number.isInteger(invocation.reportedRestart.exit) && invocation.reportedRestart.exit >= 0 && + invocation.reportedRestart.exit <= 255 + ? { resource: invocation.reportedRestart.resource, exit: invocation.reportedRestart.exit } + : null, + targetMatches: input.targetMatches, + stdout: await textEvidence(invocation.stdout), + stderr: await textEvidence(invocation.stderr), + log: safeLog, + linkedState: linked.length === 0 + ? 'missing_reference' + : linked.length === 1 + ? 'selected' + : 'ambiguous_reference', + linkedLog: linkedLog ? safeLinked : null, + }; +} + +/** Evidence retention never changes an already-executed invocation's result. */ +export async function withInvocationEvidence( + run: () => Promise, + collect: () => Promise, +): Promise { + try { + return await run(); + } finally { + try { + await collect(); + } catch { + console.warn('Owned invocation diagnostic unavailable; original outcome preserved.'); + } + } +} diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts new file mode 100644 index 0000000000..7109144d86 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts @@ -0,0 +1,207 @@ +import { saveOwnedInvocationDiagnostics } from './owned-invocation-diagnostic.ts'; +import { assert, assertEquals, assertRejects } from '@std/assert'; +import { join } from '@std/path'; +import { + invocationDiagnostic, + ownedDiagnosticFile, + selectedInvocationLog, + withInvocationEvidence, +} from './invocation-diagnostic.ts'; +import { stopAndProbe } from './cleanup.ts'; + +const times = { startedAt: '2026-01-01T00:00:00.000Z', completedAt: '2026-01-01T00:00:02.000Z' }; +const safeDetail = JSON.stringify({ + resourceKind: 'container', + resourceName: 'redis', + errorCode: 'in_use', + Config: { Env: ['SECRET_ENV_SENTINEL'] }, + message: 'SECRET_MESSAGE_SENTINEL', +}); + +Deno.test('both output streams retain only safe details; exact linked logs are bounded and private', async () => { + const root = await Deno.makeTempDir(); + try { + const home = join(root, 'home'), logs = join(home, '.aspire', 'cli', 'logs'); + await Deno.mkdir(logs, { recursive: true }); + await Deno.mkdir(join(root, '.netscript')); + const uid = (await Deno.stat(root)).uid; + if (uid === null) throw new Error('fixture requires filesystem UID'); + const log = join(logs, 'cli_20260101T000001_deadbeef.log'); + const app = join(logs, 'cli_20260101T000000000_detach-child_deadbeef.log'); + await Deno.writeTextFile(app, safeDetail); + await Deno.writeTextFile(log, safeDetail + '\n' + app + '\nSECRET_LOG_SENTINEL'); + const invocation = { + ...times, + code: 16, + stdout: safeDetail + '\n' + log, + stderr: 'summary SECRET_STDERR_SENTINEL', + }; + const result = await invocationDiagnostic({ + invocation, + logRoot: logs, + uid, + ordinal: 1, + operation: 'stop', + targetMatches: true, + }); + assertEquals(result.nativeExit, 16); + assertEquals(result.stdout.records.length, 1); + assertEquals(result.stderr.records.length, 0); + assertEquals(result.log.status, 'available'); + assert(result.linkedLog && 'status' in result.linkedLog); + assertEquals(result.linkedLog.status, 'available'); + await saveOwnedInvocationDiagnostics({ + projectRoot: root, + appHost: join(root, 'apphost.cs'), + kind: 'cleanup', + home, + uid, + transcripts: [invocation], + survivorCounts: { ownedContainers: 0, foreignContainers: 1, unprovenContainers: 2 }, + }); + const output = await Deno.readTextFile(join(root, '.netscript/e2e-cleanup-diagnostic.json')); + assert(!output.includes('SECRET_')); + assert(!output.includes(log)); + assert(!output.includes(home)); + assert(!output.includes('Config')); + assert(output.includes('in_use')); + assert(output.includes('not_collected')); + await Deno.writeTextFile(log, 'x'.repeat(300000) + '\n' + safeDetail); + const bounded = await selectedInvocationLog(log, logs, invocation, uid); + assertEquals(bounded.status, 'available'); + if (bounded.status === 'available') { + assertEquals(bounded.readBytes, 256 << 10); + assert(bounded.truncated); + } + } finally { + await Deno.remove(root, { recursive: true }); + } +}); + +Deno.test('missing, foreign, escaped, symlink and ambiguous log evidence fail closed', async () => { + const root = await Deno.makeTempDir(); + try { + const uid = (await Deno.stat(root)).uid; + if (uid === null) throw new Error('fixture requires filesystem UID'); + const path = join(root, 'cli_20260101T000001_deadbeef.log'), + invocation = { ...times, code: 1, stdout: '', stderr: '' }; + assertEquals((await selectedInvocationLog(path, root, invocation, uid)).status, 'missing'); + assertEquals( + (await selectedInvocationLog( + join(root, '../cli_20260101T000001_deadbeef.log'), + root, + invocation, + uid, + )).status, + 'refused', + ); + await Deno.writeTextFile(path, safeDetail); + assertEquals((await selectedInvocationLog(path, root, invocation, uid + 1)).status, 'refused'); + const identity = { + file: true, + symlink: false, + uid, + expectedUid: uid, + path, + actualPath: path, + root, + actualRoot: root, + }; + assert(ownedDiagnosticFile(identity)); + assert(!ownedDiagnosticFile({ ...identity, symlink: true })); + assert(!ownedDiagnosticFile({ ...identity, actualPath: join(root, 'different') })); + assert(!ownedDiagnosticFile({ ...identity, actualRoot: join(root, 'different') })); + const missing = await invocationDiagnostic({ + invocation, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: true, + }); + assertEquals(missing.log.status, 'missing_reference'); + const ambiguous = await invocationDiagnostic({ + invocation: { + ...invocation, + stdout: path + '\n' + join(root, 'cli_20260101T000002_cafebabe.log'), + }, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: true, + }); + assertEquals(ambiguous.log.status, 'ambiguous_reference'); + const refused = await invocationDiagnostic({ + invocation: { ...invocation, stdout: path }, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: false, + }); + assertEquals(refused.log.status, 'refused'); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); + +Deno.test('collector rejection cannot mask original failure or turn successful work into failure', async () => { + const original = new Error('original invocation failure'); + let collected = 0; + const error = await assertRejects(() => + withInvocationEvidence(() => Promise.reject(original), () => { + collected++; + return Promise.reject(new Error('SECRET_COLLECTOR')); + }) + ); + assertEquals(error, original); + assertEquals(collected, 1); + assertEquals( + await withInvocationEvidence( + () => Promise.resolve(17), + () => Promise.reject(new Error('SECRET_COLLECTOR')), + ), + 17, + ); +}); + +Deno.test('actual stop-and-probe retains nonzero outcome and exact command count with diagnostic failure', async () => { + const root = await Deno.makeTempDir(); + let retained = 0; + const calls: string[][] = []; + try { + await assertRejects( + () => + stopAndProbe( + join(root, 'apphost.cs'), + root, + false, + join(root, '.netscript/cleanup-private.json'), + { + run: (command, args) => { + calls.push([command, ...args]); + return Promise.resolve( + command === 'aspire' + ? { ...times, code: 16, stdout: safeDetail, stderr: 'original stop failure' } + : { code: 0, stdout: '', stderr: '' }, + ); + }, + diagnostic: (transcripts, evaluation) => { + retained++; + assertEquals(transcripts.length, 1); + assertEquals(transcripts[0].code, 16); + assertEquals(evaluation?.ownedContainers.length, 0); + return Promise.reject(new Error('SECRET_COLLECTOR')); + }, + }, + ), + Error, + 'Aspire stop did not complete: original stop failure', + ); + assertEquals(calls.filter((call) => call[0] === 'aspire').length, 1); + assertEquals(retained, 1); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts new file mode 100644 index 0000000000..98caf96f47 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts @@ -0,0 +1,70 @@ +/** Credential-safe artifact construction and owned-file publication for E2E evidence. */ +import { isAbsolute, join, relative, resolve } from '@std/path'; +import { type CapturedInvocation, invocationDiagnostic } from './invocation-diagnostic.ts'; + +/** Collector errors are diagnostic only; the caller's original cleanup result must propagate. */ +export async function saveOwnedInvocationDiagnostics(input: { + readonly projectRoot: string; + readonly appHost: string; + readonly kind: 'cleanup' | 'restart'; + readonly home: string; + readonly uid: number; + readonly transcripts: readonly CapturedInvocation[]; + readonly survivorCounts?: { + readonly ownedContainers: number; + readonly foreignContainers: number; + readonly unprovenContainers: number; + }; +}) { + const { projectRoot, kind } = input; + const delta = relative(resolve(projectRoot), resolve(input.appHost)); + const targetMatches = !delta.startsWith('..') && !isAbsolute(delta); + const commands = []; + for (const [index, invocation] of input.transcripts.slice(0, 4).entries()) { + commands.push( + await invocationDiagnostic({ + invocation, + ordinal: index + 1, + operation: kind === 'cleanup' ? 'stop' : 'restart', + targetMatches, + logRoot: join(input.home, '.aspire', 'cli', 'logs'), + uid: input.uid, + }), + ); + } + // Construct the complete upload boundary here; raw receipts/Config.Env are never accepted. + const counts = input.survivorCounts; + const value = { + schema: 1, + kind, + target: targetMatches ? delta : null, + targetMatches, + processes: 'not_collected', + survivorCounts: counts + ? { + ownedContainers: counts.ownedContainers, + foreignContainers: counts.foreignContainers, + unprovenContainers: counts.unprovenContainers, + } + : null, + commands, + }; + const parent = join(resolve(projectRoot), '.netscript'); + if (await Deno.realPath(projectRoot) !== resolve(projectRoot)) { + throw new Error('diagnostic_project_refused'); + } + const info = await Deno.lstat(parent); + if ( + !info.isDirectory || info.isSymlink || info.uid !== input.uid || + await Deno.realPath(parent) !== parent + ) throw new Error('diagnostic_directory_refused'); + const output = join(parent, `e2e-${kind}-diagnostic.json`); + const file = await Deno.makeTempFile({ dir: parent, prefix: '.diagnostic-' }); + try { + await Deno.writeTextFile(file, JSON.stringify(value) + '\n'); + if (await Deno.realPath(parent) !== parent) throw new Error('diagnostic_directory_changed'); + await Deno.rename(file, output); + } finally { + await Deno.remove(file).catch(() => {}); + } +} diff --git a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts index 7b50084231..0581c1aafb 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts @@ -145,6 +145,7 @@ async function cleanup(repoRoot: string, projectRoot: string): Promise { '--allow-read', '--allow-write', '--allow-run=aspire,docker', + '--allow-env=HOME,USERPROFILE', join(repoRoot, 'packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts'), join(projectRoot, 'aspire/apphost.mts'), projectRoot, diff --git a/packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts b/packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts index a2dce334df..5ee5095e4e 100644 --- a/packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts +++ b/packages/mcp/src/infrastructure/export-surfaces/export-surface-corpus.generated.ts @@ -187,7 +187,7 @@ export const EXPORT_SURFACE_ROWS: readonly (readonly [string, string, string, st ["fresh-ui","./tokens","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",6323,32], - ["kv",".","3VlRbxs5Dv4rRHBAEpzj4nbv7sFJk2bbHq5Iu1s02fYhDmB5hrZ1npEGksaOG+S/H0hJM9LESRcL3Mu9tB4NhyIp8vtI5fb24NLpWhZvV1isD0bh6VPrhJNadQtf0LaVOxgdFJW2eLWhXwaFw4/i+44f36HSV5vLUjQOzcHoYInusnByg5+N3sgyrrEs//9ZuJX//UVs4/IXLKV9q5XCgvb/l9H1e0XvpL3afFDSSVHJ71jyyjfhipWYV3gwOrjavCXLyvfGaNrqatNr6dfeK2d2/le3doV+5aO07reG5C0/J3Zfba4xe3fttKFdP2GtzS5126ANTl6vhMGS7VjI5cHooDOXX/PT+w0qFx/6Dfjxs8GFvB8sXjuDoj64G90eSOXQLERBdrhdg5eVFCSXri9axRHIfxaVsPbZt3/yZ1Qa/0/NiGvPmfnc+j4dyZbPif6R3/2WWSwhqQZ4gDXuJsApcgobNJaOwom6mUCr1kpvFTwGXZAXDryOEum+kBYTPIBeT2CudYVC5fovJmCdkWrJ+oXdqQKi4xBK8Oh4Ap+NrqXFs42W5XkSHEiL86jgDLyYQJ6SxxPIU5JDDFkhg6ybCmtUzqbC8AAFmWrawmlztN5cTPi78dVmBI1wq86B41NYb7pw0UOwOVljh8okFAZFqVW1A9s2jTbOV3oiEEGDYtCpWaIbPn8Sapet2YFMiRU6zJZWwmbPlbT5N4IPMVtiD7KV2+tdPdfVmM/unbSNtniXSWzJp6crV7izT1c9GGTrqGxr8LcGVbbc6Kry0m9XQi3xWWUf5XLltkj/7rGCfpMpv6kidYzzscuyJxifSA7kXkzDmMZJhmXZ3PFFrn9QF11S/HijkKvDTfazzzNODRiJpEJ+5lKdU0eWWIPwhOnjmEpEGwRp99ZhxmjwABz67lVObvF1jzSB685ueiQ6HwKaqFqcwM1L0Bb3i7ukVV+jtWKJsdJHoD1XXUyAxQN1HfcYyRs/A40ZAcMDNJyknbGVrKW7mIBq6zmaU7BOGHoOr1GV/YNBcggvEsAgu6V1qIrdxR7w7tn+Wev6DgAeAO8bafCD6gx6En0+YsB7h6q0cNmjAJ0yPFC2ZWdz1J9MkqfxrQeuXmQUDy8IpLFPTR1SRAd4e3cLIgSAe9+HaJ57TMzND/tP8nM8nnjXPzg05PhZl5bn5x1AP4mD7fzaG4qAvwVxdC86gjpw797PU+Y9TwB74PuzsJ3JJaUx6AD/GF8epxTntOEq+iSas1hJlD1iiRyr80SYsRmNHUijOztCaiUDo3NbeQyvz4HNTTX4svq2V08f4k6cE52j+m8UzQR+kUqYHf0+e9+9imY+4fH+6xtZo7mYwBd0rVE3uwbPLLoPVDAbUZ3/Mcr/f2XyokKRUucpWPk9N4KqYuDuXLc5N5+CaJpqF1vQfGsjnU+nbNlgrTd71iu5b1VYi8Y96TgYivts4N45awVOQWknF7uYdcN+YsDjYYTa19/2CJtTO/OFB3BGwIjmp3kzSg6X0v5uquHSr6JG24gCkxd2LZtrNBtZ4DtpC71BQ+QRMnKA+GmxR9SPLPDw4+zm1HgBCFOAT4fF2MP7ufDs5jzLslxhxqhPFGbj5hPc7mGFoHuf7+HlD9uNvlE1uJG6tV9pvSflUyBGTh9ljaEzeSccPtOtnIL0vdjFBJxpcZ+JPX/3st0JWLlUvHI518Zd81NfZknnYcT25SzIItklw8ACatMj/KVtzVo2oakcbMJ9SnbWaaj7roXG2a8+QsAUCa3FEua7gHZQ6LoRBk+EKk/sVjSgG/SVa8fdfU9HpsnbmLxe2yxk9ziC6Iy+DqOtYZjHEhZG1yBU3LtTRrLc3oJQpQdAcCsEy2UNIrCpdcIhy/I8CwJmSaHNwK0EbWZ1tUG7T4FWsJDGOgrCeKreNMKImriYQMOfhqhiOsjvweUNGiNLtAyoEstMzVS98e7BJVTi+w4W2myFKWlaj9vORbH2YUpsuvoKlVxgsSv4xopmkBMlaHzqvltoA7M3Cp0tjGzcq/VmRlbjvaC2AmazmbNTxa0ErDfwGsRWSOdHb92gItQ8jQJR6WtQuM3H+qP1huRmsxmfGXtDlhatMahctQPBc12HqiOQi2GYVsJyMhHvluM+LDcrHH4O5Jdqq2oGc1zw0JPp8plDp5gGLD9rK9WyQqfVnzhHLoHuEEVRoLW5wf0ZhbDlgaHo0UuikyRKUpHqEblHUmWgCSyhxIVoK7c/LNqkoqnuQSCM2MIsDKszkIR5qkDYrtCbFazuwiz99Q1cff2fBKlVJZpqR5kejY42TdUbtzJ6a+FbNG6YA9JSHxC/ZE9FCQJ46iYzw0Qbr74YO5KsBFQbabSi7jqJ6yUobWo/hAddv3/56GOkFUIhFMzTsyE4YWDcrtCtcC/wUG7PEVUfrSzFZ0Qxs+QcYm4C3kvr7JMtRJz1+/GAvsszvNDKGVG4/uz8R76L6E7fafrdYOFeMCiMn9Ss+q24LYDLzx/IuMsE1ykbw1F5mYWQFYEXFqK1CNLZLixbKnnu8gmUKSUY6QjCdVuVfL7hIFlt0Ij3K9FaIg5SZtD3UjBvyyU60nSFuxPuDwCp6xzwx4x7/xlTxcw38Uw2vwiL4McwAk6yuzVIG/Q0Ra73Rc0M91kbx1P4Ghm8a+H4e1FVmehUTdXNSlrKjYavaYjolS+jaueJ1EnStJVu1RXqFe7YvEj2DOqRLRPzY5M6INZnGANWWDXBg72aeSDq47LuQhomzDS9puqyqjpP+6wER/72/YzV8Cu6ayYjaESxFku0XFEGayHVVIXzPxFLpa2TxR66kjU5Bw+Dm+VHf7iHGd0dnpJxnr/y67K9NEYkNlWvXsEvwqbthZ0qz4y2C83tYWvR2MMRHP7tp58P70bwAErUOIHDy0oWeAiPPXWSaMeuXsdyjw76IJUJM+g+MbaSbkboiH0nPlWcdfw93VlaF7JfL4I+Tpb+KizqvYPH42N4mCrgWwVd4bjSyyP+eLym3t7/5OOnzR/D/t8oTfG+qWQhfd/UmgKhFkos/fkfMTr/NP75r8eT6FtL6Aa20A2WLx9FiEUvGSK/xh0F/JANOiTJV6/gsnW6Fk4WvpgYVTyAsQJCUsoe36N81ZVwsuo7Je781oiN5bothRPExo3RRFtQ87VM6EjRpUXFPSWXjkPrLOGUtKQeS5pRZOlR0bTqSa15Km2ZnfIyjeBMX7znjj+ux1JiiDCYIW0hGjGXlXQSPdwESCAIE9UJTT6g55aGBI/UC8aswl/sjwM89XsMB08CTOnhvzGyFmaXCC+0mSpucIvQ33NMFWLZ29k2pXC81bNVzZfzP67mpF31fw7oqoI5EIjQ5EIWfNXho+3d3FcmNGtaDsdm7G9fbp/Wd7Ly93/88/DuLhYN6Us1kSKvMgjkdTWjS+u/PLAElddjsKycdKs0nD3OyCOAx6Te2DPKT3aK2ycQoZ7hSKqianluoHIikePnnE19DTdIt4d4j0XLR3fY+ZYZ/j4KhHOc5G687h65ML0Dj7HkeKAHrKVzsTCFCumIZZaIQ0pKuppwPJ6YXhaKN2MsehlKRIYbCF8//s5CVGDbuc8yf2EkSqnQ+hr6F7WvJ40wbtczXGhCYUayu9kYrunSymtnHWEs4cjTiUh3OlXpLhaEQR74xvBOGupwOu1hAqXmOfZDoqBxvMLSA+t4qsK0mIx6NDX66pRKoen9CJcRI8KmbrrVvrPj7px4l6OzSD5Pe1elg47gadvE9oj7MgUoDE15dNcxVQb/gwV3ZsGA0yQyBp2QjA7ZABB2O+xmQN9KThXyn4rmuBIbqc0YblbSlMPzqEVs8qgeKiEV+FvAeN7jg7u7/wI=","7Eef6iYOVnq4iYHYfwXg1jhGQNjrLTFz2twc+D4AGzc=",8861,30], + ["kv",".","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",9468,32], ["kv","./kvdex","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",7982,23], From bb0ae41bf6a0b3ebf5dcff4468adbbc72c5b46e6 Mon Sep 17 00:00:00 2001 From: rickylabs <129366361+rickylabs@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:24:25 +0100 Subject: [PATCH 3/5] fix(kv): classify driver errors and preserve direct E2E command ownership Use the pinned driver error tuple, collect diagnostics after the original command settles, and stage safe artifacts outside scaffold data. Import the complete canonical surface inventory without changing version policy. Refs #2648 --- .github/workflows/e2e-cli.yml | 6 +- .../fixtures/aspire-surface-manifest.tsv | 5 + .../e2e/src/application/gates/command-gate.ts | 7 + .../gates/scaffold/database-gates.ts | 45 +++-- .../gates/scaffold/gate-factory.ts | 4 +- .../scaffold/runtime/evidence/cleanup.ts | 6 +- .../evidence/database-generate-diagnostic.ts | 121 ++++++-------- .../database-generate-diagnostic_test.ts | 154 +++++++++++++----- .../runtime/evidence/invocation-diagnostic.ts | 5 +- .../evidence/invocation-staging_test.ts | 103 ++++++++++++ .../evidence/owned-invocation-diagnostic.ts | 108 +++++++++--- .../scaffold/verify-documented-scaffold.ts | 1 + .../cli/e2e/src/domain/gate-definition.ts | 12 +- packages/kv/adapters/redis/atomic-result.ts | 10 +- .../kv/tests/redis-atomic-outcomes_test.ts | 40 ++++- 15 files changed, 440 insertions(+), 187 deletions(-) create mode 100644 packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-staging_test.ts diff --git a/.github/workflows/e2e-cli.yml b/.github/workflows/e2e-cli.yml index 22f5d1565e..ff9ec067f0 100644 --- a/.github/workflows/e2e-cli.yml +++ b/.github/workflows/e2e-cli.yml @@ -389,8 +389,7 @@ jobs: .llm/tmp/e2e-report-scaffold-runtime*.ndjson .llm/tmp/e2e-image-pulls.json .llm/tmp/cli-e2e/*/.netscript/e2e/listener-unreachable-receipt.json - .llm/tmp/cli-e2e/documented-scaffold/**/.netscript/e2e-cleanup-diagnostic.json - .llm/tmp/cli-e2e/*/.netscript/e2e-restart-diagnostic.json + .llm/tmp/e2e-invocation-diagnostics/*-diagnostic.json .llm/tmp/gate-receipts/scaffold-runtime/agent.aspire-mcp-smoke* include-hidden-files: true if-no-files-found: ignore @@ -509,8 +508,7 @@ jobs: .llm/tmp/e2e-report-scaffold-runtime-sqlite*.ndjson .llm/tmp/e2e-image-pulls.json .llm/tmp/cli-e2e/*/.netscript/e2e/listener-unreachable-receipt.json - .llm/tmp/cli-e2e/documented-scaffold/**/.netscript/e2e-cleanup-diagnostic.json - .llm/tmp/cli-e2e/*/.netscript/e2e-restart-diagnostic.json + .llm/tmp/e2e-invocation-diagnostics/*-diagnostic.json .llm/tmp/gate-receipts/scaffold-runtime-sqlite/agent.aspire-mcp-smoke* .llm/tmp/showcase-ai-browser/ include-hidden-files: true diff --git a/.llm/tools/validation/fixtures/aspire-surface-manifest.tsv b/.llm/tools/validation/fixtures/aspire-surface-manifest.tsv index 4512961013..e3ea7eee99 100644 --- a/.llm/tools/validation/fixtures/aspire-surface-manifest.tsv +++ b/.llm/tools/validation/fixtures/aspire-surface-manifest.tsv @@ -365,9 +365,14 @@ packages/cli/e2e/src/application/gates/scaffold/runtime/credential-secret-surfac packages/cli/e2e/src/application/gates/scaffold/runtime/dashboard-config_test.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/dashboard-config.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/describe-capture.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/describe-follow.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/doctor.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) +packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/resource-command.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/listener-fault-controller.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) packages/cli/e2e/src/application/gates/scaffold/runtime/listener-readiness-gates.ts e2e S2/S3/S10 runtime verification (S2); 13.5.3 fixtures (S3); gate upgrades + agent.aspire-mcp-smoke (S10/S9) diff --git a/packages/cli/e2e/src/application/gates/command-gate.ts b/packages/cli/e2e/src/application/gates/command-gate.ts index a84eee32db..e36b99bb2b 100644 --- a/packages/cli/e2e/src/application/gates/command-gate.ts +++ b/packages/cli/e2e/src/application/gates/command-gate.ts @@ -38,6 +38,7 @@ export class CommandGate { for (let attempt = 1; attempt <= maxAttempts; attempt++) { const started = performance.now(); + const startedAt = new Date().toISOString(); const result = await this.executor.run({ cwd: this.definition.cwd(context), command: this.definition.command(context), @@ -46,6 +47,12 @@ export class CommandGate { failureHint: this.definition.failureHint, }); const durationMs = Math.round(performance.now() - started); + const completedAt = new Date().toISOString(); + try { + await this.definition.afterCommand?.({ context, result, startedAt, completedAt }); + } catch { + console.warn('Command diagnostic unavailable; original outcome preserved.'); + } const missingOutput = (this.definition.stdoutIncludes ?? []).filter((value) => !result.stdout.includes(value) ); diff --git a/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts b/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts index fd4245c518..18af765509 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/database-gates.ts @@ -1,3 +1,4 @@ +import { databaseGenerateEvidence } from './runtime/evidence/database-generate-diagnostic.ts'; import { join } from '@std/path'; import { GATE, GATE_PHASE } from '../../../domain/cli-surface.ts'; import type { GateDefinition } from '../../../domain/gate-definition.ts'; @@ -76,32 +77,24 @@ export function createDatabaseGates(): readonly GateDefinition[] { ], (context) => context.project.projectRoot, ), - commandGate( - GATE.DATABASE_GENERATE, - 'Generate database clients', - GATE_PHASE.DATABASE, - (context) => [ - 'deno', - 'run', - '--allow-all', - join( - context.project.repoRoot, - 'packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts', - ), - context.project.projectRoot, - context.project.appHost, - '--', - ...cli( - context, - 'db', - 'generate', - '--project-root', - context.project.projectRoot, - '--db', - context.request.options.database, - ), - ], - ), + { + ...commandGate( + GATE.DATABASE_GENERATE, + 'Generate database clients', + GATE_PHASE.DATABASE, + (context) => + cli( + context, + 'db', + 'generate', + '--project-root', + context.project.projectRoot, + '--db', + context.request.options.database, + ), + ), + afterCommand: databaseGenerateEvidence(), + }, commandGate( GATE.DATABASE_DEPLOY, 'Apply pending migrations without creating one', diff --git a/packages/cli/e2e/src/application/gates/scaffold/gate-factory.ts b/packages/cli/e2e/src/application/gates/scaffold/gate-factory.ts index 8c75b05e8e..68f49cf7c4 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/gate-factory.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/gate-factory.ts @@ -4,8 +4,8 @@ import { PACKAGE_SOURCE } from '../../../domain/extension-axes.ts'; import { resolve } from '@std/path'; import type { CommandFactory, + CommandGateDefinition, CommandGateRetryPolicy, - GateDefinition, GateFailureClass, HttpGateDefinition, } from '../../../domain/gate-definition.ts'; @@ -57,7 +57,7 @@ export function commandGate( retry?: CommandGateRetryPolicy, timeoutMs?: number, failureClass?: GateFailureClass, -): GateDefinition { +): CommandGateDefinition { return { id, title, diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts index c82e1652fe..572acda1b9 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/cleanup.ts @@ -185,6 +185,7 @@ export async function stopAndProbe( cleanup: boolean, receiptPath: string, options: { + readonly runnerRoot?: string; readonly run?: typeof capture; readonly wait?: (ms: number) => Promise; readonly diagnostic?: ( @@ -263,6 +264,7 @@ export async function stopAndProbe( projectRoot, appHost, kind: 'cleanup', + runnerRoot: options.runnerRoot, home, uid, transcripts, @@ -416,9 +418,9 @@ function record(value: unknown, label: string): Record { } if (import.meta.main) { - const [appHost, projectRoot, cleanupValue, receiptPath] = Deno.args; + const [appHost, projectRoot, cleanupValue, receiptPath, runnerRoot] = Deno.args; if (!appHost || !projectRoot || !cleanupValue || !receiptPath) { throw new Error('cleanup requires AppHost, project root, cleanup boolean, and receipt path'); } - await stopAndProbe(appHost, projectRoot, cleanupValue === 'true', receiptPath); + await stopAndProbe(appHost, projectRoot, cleanupValue === 'true', receiptPath, { runnerRoot }); } diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts index 121b6a1770..ed7cbeba6a 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts @@ -1,3 +1,4 @@ +import type { CommandObservation } from '../../../../../domain/gate-definition.ts'; /** Test-only evidence around the original database.generate command; no additional Aspire calls. */ import { saveOwnedInvocationDiagnostics } from './owned-invocation-diagnostic.ts'; import type { CapturedInvocation } from './invocation-diagnostic.ts'; @@ -14,80 +15,54 @@ export function reportedRestartFailure(text: string, appHost: string) { return { resource: match[1], exit: Number(match[2]) }; } -/** Capture one command and return exactly its native exit; diagnostic failure cannot replace it. */ -export async function databaseGenerateWithEvidence(input: { - readonly command: readonly string[]; - readonly appHost: string; - readonly run?: (command: readonly string[]) => Promise; - readonly emit?: (stdout: string, stderr: string) => Promise; - readonly collect: (invocation: CapturedInvocation) => Promise; -}): Promise { - const run = input.run ?? (async (command: readonly string[]) => { - const startedAt = new Date().toISOString(); - const result = await new Deno.Command(command[0], { - args: command.slice(1), - stdin: 'null', - stdout: 'piped', - stderr: 'piped', - }).output(); - return { - startedAt, - completedAt: new Date().toISOString(), - code: result.code, - stdout: new TextDecoder().decode(result.stdout), - stderr: new TextDecoder().decode(result.stderr), - }; - }); - const invocation = await run(input.command); - const emit = input.emit ?? (async (stdout, stderr) => { - await Deno.stdout.write(new TextEncoder().encode(stdout)); - await Deno.stderr.write(new TextEncoder().encode(stderr)); - }); - try { - await emit(invocation.stdout, invocation.stderr); - } finally { - try { - await input.collect({ - ...invocation, +/** Build a diagnostic observer for the existing direct command executor, never a subprocess wrapper. */ +export function databaseGenerateEvidence( + collect: ( + input: { + readonly projectRoot: string; + readonly appHost: string; + readonly runnerRoot: string; + readonly invocation: CapturedInvocation; + }, + ) => Promise = save, +): (observation: CommandObservation) => Promise { + return async ({ context, result, startedAt, completedAt }) => { + const appHost = context.project.appHost; + await collect({ + projectRoot: context.project.projectRoot, + appHost, + runnerRoot: context.project.repoRoot, + invocation: { + code: result.code, + stdout: result.stdout, + stderr: result.stderr, + startedAt, + completedAt, process: 'database_cli', - reportedRestart: reportedRestartFailure( - invocation.stderr + '\n' + invocation.stdout, - input.appHost, - ), - }); - } catch { - console.warn('Owned restart diagnostic unavailable; original command outcome preserved.'); - } - } - return invocation.code; + timedOut: result.timedOut, + reportedRestart: reportedRestartFailure(result.stderr + '\n' + result.stdout, appHost), + }, + }); + }; } - -if (import.meta.main) { - const [projectRoot, appHost, separator, ...command] = Deno.args; - if ( - !projectRoot || !appHost || separator !== '--' || command[0] !== 'deno' || - !command.includes('generate') || !command.includes('--project-root') || - !command.includes(projectRoot) - ) { - throw new Error('Expected the existing generated-project database command'); - } - const code = await databaseGenerateWithEvidence({ - command, - appHost, - collect: async (invocation) => { - const home = Deno.env.get('HOME') ?? Deno.env.get('USERPROFILE'); - const uid = (await Deno.stat(projectRoot)).uid; - if (!home || uid === null) throw new Error('diagnostic_owner_unavailable'); - await Deno.mkdir(`${projectRoot}/.netscript`, { recursive: true }); - await saveOwnedInvocationDiagnostics({ - projectRoot, - appHost, - kind: 'restart', - home, - uid, - transcripts: [invocation], - }); - }, +async function save( + input: { + readonly projectRoot: string; + readonly appHost: string; + readonly runnerRoot: string; + readonly invocation: CapturedInvocation; + }, +): Promise { + const home = Deno.env.get('HOME') ?? Deno.env.get('USERPROFILE'); + const uid = (await Deno.stat(input.projectRoot)).uid; + if (!home || uid === null) throw new Error('diagnostic_owner_unavailable'); + await saveOwnedInvocationDiagnostics({ + projectRoot: input.projectRoot, + appHost: input.appHost, + runnerRoot: input.runnerRoot, + kind: 'restart', + home, + uid, + transcripts: [input.invocation], }); - Deno.exit(code); } diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts index 6c6cc64757..0045c2e8d9 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts @@ -1,53 +1,117 @@ -import { assertEquals } from '@std/assert'; +import { assert, assertEquals } from '@std/assert'; import { - databaseGenerateWithEvidence, + databaseGenerateEvidence, reportedRestartFailure, } from './database-generate-diagnostic.ts'; +import { CommandGate } from '../../../command-gate.ts'; +import { createDatabaseGates } from '../../database-gates.ts'; +import type { RunContext } from '../../../../../domain/run-context.ts'; +import type { GateResult } from '../../../../../domain/gate-definition.ts'; -Deno.test('database generate diagnostic runs exactly the original command and preserves failure', async () => { - const appHost = '/synthetic/project/aspire/apphost.mts'; - const text = - `Database client generated, but web restart failed (Aspire exit 16). summary\nRun: aspire resource web restart --apphost ${ - JSON.stringify(appHost) - }`; - let runs = 0, collects = 0; - const command = ['deno', 'run', 'cli.ts', 'db', 'generate']; - const code = await databaseGenerateWithEvidence({ - command, - appHost, - run: (args) => { - runs++; - assertEquals(args, command); - return Promise.resolve({ code: 1, stdout: 'stdout detail', stderr: text }); +const context: RunContext = { + request: { + suiteId: 'scaffold.runtime', + options: { + repoRoot: '/repo', + cliEntrypoint: 'packages/cli/bin/netscript.ts', + smokeRoot: '/repo/run', + projectName: 'app', + database: 'postgres', + packageSource: 'local', + plugins: [], + samples: true, + cache: true, + cleanup: true, + format: 'pretty', + commandTimeoutMs: 900000, + httpTimeoutMs: 30000, }, - emit: async () => {}, - collect: (invocation) => { - collects++; - assertEquals(invocation.code, 1); - assertEquals(invocation.process, 'database_cli'); - assertEquals(invocation.reportedRestart, { resource: 'web', exit: 16 }); + }, + project: { + repoRoot: '/repo', + cliEntrypoint: 'packages/cli/bin/netscript.ts', + smokeRoot: '/repo/run', + projectName: 'app', + projectRoot: '/repo/run/app', + appHost: '/repo/run/app/aspire/apphost.mts', + }, +}; +const appHost = context.project.appHost; +const failure = + `Database client generated, but web restart failed (Aspire exit 16). summary\nRun: aspire resource web restart --apphost ${ + JSON.stringify(appHost) + }`; + +Deno.test('database generate remains the direct child; evidence follows original success failure and timeout settlement', async () => { + const definition = createDatabaseGates().find((g) => g.id === 'database.generate'); + assert(definition?.kind === 'command'); + assert(definition.afterCommand); + const expected = [ + 'deno', + 'run', + '-A', + '/repo/packages/cli/bin/netscript.ts', + 'db', + 'generate', + '--project-root', + '/repo/run/app', + '--db', + 'postgres', + ]; + assertEquals(definition.command(context), expected); + for ( + const outcome of [{ code: 0, timedOut: false }, { code: 1, timedOut: false }, { + code: 124, + timedOut: true, + }] + ) { + let calls = 0, collected = 0, settled = false; + const afterCommand = databaseGenerateEvidence((input) => { + assert(settled); + collected++; + assertEquals(input.invocation.code, outcome.code); + assertEquals(input.invocation.timedOut, outcome.timedOut); + assertEquals(input.invocation.process, 'database_cli'); + assertEquals( + input.invocation.reportedRestart, + outcome.code === 1 ? { resource: 'web', exit: 16 } : undefined, + ); return Promise.reject(new Error('SECRET_COLLECTOR')); - }, - }); - assertEquals(code, 1); - assertEquals(runs, 1); - assertEquals(collects, 1); - assertEquals(reportedRestartFailure(text, '/foreign/apphost.mts'), undefined); - assertEquals(reportedRestartFailure(text.replace('exit 16', 'exit 999'), appHost), undefined); + }); + const gate = new CommandGate({ ...definition, afterCommand }, { + run: async (request) => { + calls++; + assertEquals(request.command, expected); + assertEquals(request.timeoutMs, 900000); + await Promise.resolve(); + settled = true; + return { + command: request.command, + cwd: request.cwd, + ...outcome, + stdout: 'detail', + stderr: outcome.code === 1 ? failure : '', + }; + }, + }); + let thrown: unknown; + let result: GateResult | undefined; + try { + result = await gate.execute(context); + } catch (error) { + thrown = error; + } + assertEquals(thrown, undefined, 'evidence collection must preserve original settlement'); + assert(result); + assertEquals(result.verdict, outcome.code === 0 ? 'passed' : 'failed'); + assertEquals(result.attempts[0].exitCode, outcome.code); + assertEquals(result.retried, false); + assertEquals(calls, 1); + assertEquals(collected, 1); + } }); -Deno.test('database generate diagnostic preserves success and does not invent a restart outcome', async () => { - let collected = 0; - const code = await databaseGenerateWithEvidence({ - command: ['deno'], - appHost: '/synthetic/apphost.mts', - run: () => Promise.resolve({ code: 0, stdout: 'success', stderr: '' }), - emit: async () => {}, - collect: (invocation) => { - collected++; - assertEquals(invocation.reportedRestart, undefined); - return Promise.resolve(); - }, - }); - assertEquals(code, 0); - assertEquals(collected, 1); +Deno.test('nested restart result requires the exact reported target and never becomes a captured process status', () => { + assertEquals(reportedRestartFailure(failure, appHost), { resource: 'web', exit: 16 }); + assertEquals(reportedRestartFailure(failure, '/foreign/apphost.mts'), undefined); + assertEquals(reportedRestartFailure(failure.replace('exit 16', 'exit 999'), appHost), undefined); }); diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts index d3588cb5b4..14885ed996 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts @@ -23,6 +23,7 @@ export interface CapturedInvocation { readonly startedAt?: string; readonly completedAt?: string; readonly process?: 'aspire' | 'database_cli'; + readonly timedOut?: boolean; readonly reportedRestart?: { readonly resource: string; readonly exit: number }; } export interface DiagnosticRecord { @@ -212,7 +213,9 @@ export async function invocationDiagnostic(input: { return { ordinal: input.ordinal, operation: input.operation, - nativeExit: invocation.code, + nativeExit: invocation.process === 'database_cli' ? null : invocation.code, + executorExit: invocation.process === 'database_cli' ? invocation.code : null, + timedOut: invocation.timedOut ?? false, process: invocation.process ?? 'aspire', reportedRestart: invocation.reportedRestart && NAMES.has(invocation.reportedRestart.resource) && Number.isInteger(invocation.reportedRestart.exit) && invocation.reportedRestart.exit >= 0 && diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-staging_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-staging_test.ts new file mode 100644 index 0000000000..8ab4015402 --- /dev/null +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-staging_test.ts @@ -0,0 +1,103 @@ +import { assert, assertEquals, assertRejects } from '@std/assert'; +import { join } from '@std/path'; +import { + INVOCATION_ARTIFACT_DIRECTORY, + saveOwnedInvocationDiagnostics, +} from './owned-invocation-diagnostic.ts'; + +Deno.test('known nested workspace diagnostics stage flat without visiting unrelated protected data', async () => { + const supplied = Deno.env.get('NETSCRIPT_E2E_DIAGNOSTIC_FIXTURE_ROOT'); + const runner = supplied ?? await Deno.makeTempDir(); + try { + const uid = (await Deno.stat(runner)).uid; + if (uid === null) throw new Error('fixture requires filesystem UID'); + for (const variant of ['skip-seed-handoff', 'drop-link', 'restored']) { + const projectRoot = join(runner, 'documented', variant, 'app'); + await Deno.mkdir(projectRoot, { recursive: true }); + const forbidden = join(projectRoot, '.data'); + if (!supplied) { + await Deno.mkdir(join(forbidden, 'postgres/18/docker'), { recursive: true }); + await Deno.writeTextFile(join(forbidden, 'private.txt'), 'SECRET_UNRELATED_SUBTREE'); + } + if (supplied) { + await assertRejects(async () => { + for await (const _entry of Deno.readDir(forbidden)) { /* negative permission control */ } + }, Deno.errors.NotCapable); + } + await saveOwnedInvocationDiagnostics({ + runnerRoot: runner, + projectRoot, + appHost: join(projectRoot, 'host.mts'), + kind: 'cleanup', + home: join(runner, 'home'), + uid, + transcripts: [{ code: 0, stdout: 'SECRET_RAW_SENTINEL', stderr: 'SECRET_STDERR_SENTINEL' }], + }); + } + const directory = join(runner, INVOCATION_ARTIFACT_DIRECTORY); + const files = []; + for await (const entry of Deno.readDir(directory)) files.push(entry); + assertEquals(files.length, 3); + for (const entry of files) { + assert(entry.isFile); + assert(/^cleanup-[a-f0-9]{64}-diagnostic\.json$/.test(entry.name)); + const text = await Deno.readTextFile(join(directory, entry.name)); + assert(!text.includes('SECRET_')); + assert(!text.includes(runner)); + assert(!text.includes('.data')); + const value = JSON.parse(text); + assertEquals(value.status, 'collected'); + assertEquals(value.commands[0].log.status, 'missing_reference'); + } + } finally { + if (!supplied) await Deno.remove(runner, { recursive: true }); + } +}); +Deno.test('staging refuses a foreign root or target and never broadens discovery', async () => { + const root = await Deno.makeTempDir(); + try { + const runner = join(root, 'runner'), projectRoot = join(root, 'foreign'); + await Deno.mkdir(runner); + await Deno.mkdir(projectRoot); + const uid = (await Deno.stat(root)).uid; + if (uid === null) throw new Error('fixture requires filesystem UID'); + const input = { + runnerRoot: runner, + projectRoot, + appHost: join(projectRoot, 'host.mts'), + kind: 'cleanup' as const, + home: root, + uid, + transcripts: [], + }; + await assertRejects( + () => saveOwnedInvocationDiagnostics(input), + Error, + 'diagnostic_workspace_refused', + ); + await assertRejects( + () => saveOwnedInvocationDiagnostics({ ...input, projectRoot: runner }), + Error, + 'diagnostic_target_refused', + ); + await assertRejects( + () => Deno.stat(join(runner, INVOCATION_ARTIFACT_DIRECTORY)), + Deno.errors.NotFound, + ); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); + +Deno.test('both runtime uploads select only the flat safe diagnostic files', async () => { + const source = await Deno.readTextFile( + new URL('../../../../../../../../../.github/workflows/e2e-cli.yml', import.meta.url), + ); + const paths = source.split(/\r?\n/).map((line) => line.trim()).filter((line) => + line.startsWith('.llm/tmp/') && line.includes('diagnostic') + ); + assertEquals(paths, [ + '.llm/tmp/e2e-invocation-diagnostics/*-diagnostic.json', + '.llm/tmp/e2e-invocation-diagnostics/*-diagnostic.json', + ]); +}); diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts index 98caf96f47..9770d175ff 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts @@ -1,24 +1,100 @@ -/** Credential-safe artifact construction and owned-file publication for E2E evidence. */ +/** Credential-safe artifact construction at known write sites; no directory discovery. */ import { isAbsolute, join, relative, resolve } from '@std/path'; import { type CapturedInvocation, invocationDiagnostic } from './invocation-diagnostic.ts'; -/** Collector errors are diagnostic only; the caller's original cleanup result must propagate. */ +export const INVOCATION_ARTIFACT_DIRECTORY = '.llm/tmp/e2e-invocation-diagnostics'; +const MAX_ARTIFACT_BYTES = 64 << 10; +function within(root: string, path: string): boolean { + const delta = relative(resolve(root), resolve(path)); + return delta !== '' && !delta.startsWith('..') && !isAbsolute(delta); +} +async function hash(text: string): Promise { + return [...new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)))] + .map((value) => value.toString(16).padStart(2, '0')).join(''); +} +async function ownedDirectory(path: string, uid: number): Promise { + const entry = await Deno.lstat(path); + if ( + !entry.isDirectory || entry.isSymlink || entry.uid !== uid || + await Deno.realPath(path) !== resolve(path) + ) throw new Error('diagnostic_directory_refused'); +} +async function runnerArtifactDirectory(root: string, uid: number): Promise { + const resolved = resolve(root); + await ownedDirectory(resolved, uid); + let current = resolved; + for (const name of INVOCATION_ARTIFACT_DIRECTORY.split('/')) { + current = join(current, name); + try { + await Deno.mkdir(current, { mode: 0o700 }); + } catch (error) { + if (!(error instanceof Deno.errors.AlreadyExists)) throw error; + } + await ownedDirectory(current, uid); + } + return current; +} +async function writeArtifact( + parent: string, + path: string, + value: unknown, + uid: number, +): Promise { + // Private function: only the complete explicit safe projection below reaches this boundary. + const text = JSON.stringify(value) + '\n'; + if (new TextEncoder().encode(text).length > MAX_ARTIFACT_BYTES) { + throw new Error('diagnostic_budget_exceeded'); + } + await ownedDirectory(parent, uid); + const temporary = await Deno.makeTempFile({ dir: parent, prefix: '.diagnostic-' }); + try { + await Deno.writeTextFile(temporary, text); + await ownedDirectory(parent, uid); + await Deno.rename(temporary, path); + } finally { + await Deno.remove(temporary).catch(() => {}); + } +} + +/** Collect directly into the owned flat artifact root, never recurse through workspace data. */ export async function saveOwnedInvocationDiagnostics(input: { readonly projectRoot: string; readonly appHost: string; readonly kind: 'cleanup' | 'restart'; readonly home: string; readonly uid: number; + readonly runnerRoot?: string; readonly transcripts: readonly CapturedInvocation[]; readonly survivorCounts?: { readonly ownedContainers: number; readonly foreignContainers: number; readonly unprovenContainers: number; }; -}) { +}): Promise { const { projectRoot, kind } = input; + await ownedDirectory(resolve(projectRoot), input.uid); const delta = relative(resolve(projectRoot), resolve(input.appHost)); - const targetMatches = !delta.startsWith('..') && !isAbsolute(delta); + const targetMatches = delta !== '' && !delta.startsWith('..') && !isAbsolute(delta); + if (!targetMatches) throw new Error('diagnostic_target_refused'); + const workspaceKey = await hash(resolve(projectRoot)); + let parent: string, output: string; + if (input.runnerRoot) { + if (!within(input.runnerRoot, projectRoot)) throw new Error('diagnostic_workspace_refused'); + parent = await runnerArtifactDirectory(input.runnerRoot, input.uid); + output = join(parent, `${kind}-${workspaceKey}-diagnostic.json`); + } else { + parent = join(resolve(projectRoot), '.netscript'); + await ownedDirectory(parent, input.uid); + output = join(parent, `e2e-${kind}-diagnostic.json`); + } + // A failed collector leaves an explicit unavailable record, never a fabricated complete artifact. + await writeArtifact(parent, output, { + schema: 1, + kind, + workspaceKey, + status: 'unavailable', + reason: 'collection_incomplete', + }, input.uid); const commands = []; for (const [index, invocation] of input.transcripts.slice(0, 4).entries()) { commands.push( @@ -32,12 +108,13 @@ export async function saveOwnedInvocationDiagnostics(input: { }), ); } - // Construct the complete upload boundary here; raw receipts/Config.Env are never accepted. const counts = input.survivorCounts; const value = { schema: 1, kind, - target: targetMatches ? delta : null, + workspaceKey, + status: 'collected', + target: delta, targetMatches, processes: 'not_collected', survivorCounts: counts @@ -49,22 +126,5 @@ export async function saveOwnedInvocationDiagnostics(input: { : null, commands, }; - const parent = join(resolve(projectRoot), '.netscript'); - if (await Deno.realPath(projectRoot) !== resolve(projectRoot)) { - throw new Error('diagnostic_project_refused'); - } - const info = await Deno.lstat(parent); - if ( - !info.isDirectory || info.isSymlink || info.uid !== input.uid || - await Deno.realPath(parent) !== parent - ) throw new Error('diagnostic_directory_refused'); - const output = join(parent, `e2e-${kind}-diagnostic.json`); - const file = await Deno.makeTempFile({ dir: parent, prefix: '.diagnostic-' }); - try { - await Deno.writeTextFile(file, JSON.stringify(value) + '\n'); - if (await Deno.realPath(parent) !== parent) throw new Error('diagnostic_directory_changed'); - await Deno.rename(file, output); - } finally { - await Deno.remove(file).catch(() => {}); - } + await writeArtifact(parent, output, value, input.uid); } diff --git a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts index 0581c1aafb..22f02319ef 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts @@ -151,6 +151,7 @@ async function cleanup(repoRoot: string, projectRoot: string): Promise { projectRoot, 'true', receiptPath, + repoRoot, ], projectRoot); const receipt = z.object({ evaluation: z.object({ diff --git a/packages/cli/e2e/src/domain/gate-definition.ts b/packages/cli/e2e/src/domain/gate-definition.ts index 74cdffa618..1609086549 100644 --- a/packages/cli/e2e/src/domain/gate-definition.ts +++ b/packages/cli/e2e/src/domain/gate-definition.ts @@ -1,7 +1,7 @@ import type { Evidence } from './evidence.ts'; import type { RunContext } from './run-context.ts'; import type { GateId, GatePhase } from './cli-surface.ts'; -import type { CommandOutputMode } from '../ports/command-executor.ts'; +import type { CommandOutputMode, CommandResult } from '../ports/command-executor.ts'; import type { ExecutionPlatform } from './platform.ts'; import type { HttpExchangeContract } from './http-contract.ts'; @@ -43,6 +43,14 @@ export type CommandFactory = (context: RunContext) => readonly string[]; /** Resolve a working directory from the current run context. */ export type WorkingDirectoryFactory = (context: RunContext) => string; +/** Evidence from the original awaited executor; observers never own another process. */ +export interface CommandObservation { + readonly context: RunContext; + readonly result: CommandResult; + readonly startedAt: string; + readonly completedAt: string; +} + /** Resolve an HTTP URL from the current run context. */ export type UrlFactory = (context: RunContext) => string; @@ -85,6 +93,8 @@ export interface CommandGateDefinition extends BaseGateDefinition { readonly timeoutMs?: number; /** Stable failure class for commands whose boundary is known before execution. */ readonly failureClass?: GateFailureClass; + /** Optional evidence only; a failed observer must preserve the original command result. */ + readonly afterCommand?: (observation: CommandObservation) => Promise; } /** diff --git a/packages/kv/adapters/redis/atomic-result.ts b/packages/kv/adapters/redis/atomic-result.ts index 98c3f6ad1e..83187bece5 100644 --- a/packages/kv/adapters/redis/atomic-result.ts +++ b/packages/kv/adapters/redis/atomic-result.ts @@ -6,7 +6,8 @@ import { KvAtomicCommitUnconfirmedError } from '../../application/errors.ts'; * * Null EXEC is handled by the caller as an optimistic conflict. A null detail * inside a successful tuple is valid; only its explicit null error slot proves - * command success. A command failure can leave other mutations applied. + * command success. ioredis wraps a failed command as a one-element `[Error]` + * tuple. A command failure can leave other mutations applied. * * @param result - Non-null result returned by the transport. * @param commands - Exact number of queued Redis commands. @@ -17,11 +18,14 @@ export function assertRedisAtomicResult(result: unknown, commands: number): void throw new KvAtomicCommitUnconfirmedError('malformed_result'); } for (const command of result) { - if (!Array.isArray(command) || command.length !== 2 || command[0] === undefined) { + if (!Array.isArray(command) || command.length < 1 || command.length > 2) { throw new KvAtomicCommitUnconfirmedError('malformed_result'); } - if (command[0] !== null) { + if (command[0] instanceof Error) { throw new KvAtomicCommitUnconfirmedError('command_failed'); } + if (command.length !== 2 || command[0] !== null) { + throw new KvAtomicCommitUnconfirmedError('malformed_result'); + } } } diff --git a/packages/kv/tests/redis-atomic-outcomes_test.ts b/packages/kv/tests/redis-atomic-outcomes_test.ts index c0127078b0..d0185ea4df 100644 --- a/packages/kv/tests/redis-atomic-outcomes_test.ts +++ b/packages/kv/tests/redis-atomic-outcomes_test.ts @@ -4,6 +4,13 @@ import { RedisKvAdapter } from '../redis.ts'; import type { AtomicMutation } from '../types/kv-store.ts'; type Reply = (commands: number, attempt: number) => unknown; +/** ioredis5.11.1 built/utils/index.js51–68: transaction.js passes EXEC through wrapMultiResult. + * The pinned normalizer wraps Error as [error], and ordinary details as [null, detail]. + * This source-proven fixture models that normalization before the actual owning adapter runs. + */ +function ioredisExecReplies(values: readonly unknown[]): unknown[] { + return values.map((item) => item instanceof Error ? [item] : [null, item]); +} function fixture( reply: Reply, options: { cleanupFails?: boolean; publicationFails?: boolean } = {}, @@ -84,6 +91,27 @@ const mutations: AtomicMutation[] = [ ]; const success: Reply = (count) => Array.from({ length: count }, () => [null, 'OK']); +Deno.test('pinned ioredis normalization keeps one-element Error tuples and null success details', () => { + const failure = new Error('synthetic'); + assertEquals(ioredisExecReplies(['OK', failure, null]), [[null, 'OK'], [failure], [null, null]]); +}); + +Deno.test('ioredis command failure survives failed task cleanup without notification or retry', async () => { + const f = fixture(() => ioredisExecReplies([new Error('synthetic private detail'), 'OK', 'OK']), { + cleanupFails: true, + }); + try { + const error = await assertRejects(() => f.kv.atomic([], mutations)); + assert(error instanceof Error); + assertEquals(Reflect.get(error, 'reason'), 'command_failed'); + assertEquals(Reflect.get(error, 'cause'), undefined); + assertEquals(f.notifications(), 0); + assertEquals(f.attempts(), 1); + } finally { + await f.kv.close(); + } +}); + Deno.test('Redis atomic validates all successful command tuples before notifying', async () => { const f = fixture((count) => Array.from({ length: count }, () => [null, null])); try { @@ -125,13 +153,10 @@ Deno.test('Redis repeated null EXEC retains bounded conflict failure', async () for (const failed of [0, 1, 2]) { Deno.test(`Redis command failure at position ${failed} is unconfirmed without retry or notification`, async () => { const f = fixture((count) => - Array.from( + ioredisExecReplies(Array.from( { length: count }, - (_, i) => - i === failed - ? [new Error('synthetic command payload must remain private'), null] - : [null, 'OK'], - ) + (_, i) => i === failed ? new Error('synthetic command payload must remain private') : 'OK', + )) ); try { const error = await assertRejects(() => f.kv.atomic([], mutations)); @@ -157,6 +182,9 @@ for ( ['long', [[null, 1], [null, 1], [null, 1], [null, 1]]], ['malformed tuple', [[null, 1], [null], [null, 1]]], ['missing error slot', [[null, 1], [undefined, 'OK'], [null, 1]]], + ['non-error singleton', [[null, 1], ['unexpected'], [null, 1]]], + ['non-error error slot', [[null, 1], ['unexpected', null], [null, 1]]], + ['oversized error tuple', [[null, 1], [new Error('synthetic'), null, null], [null, 1]]], ] as const ) { Deno.test(`Redis ${label} EXEC result cannot certify a complete commit`, async () => { From a06a1b431ec2cbf1245c64e956545b8b8acc7f48 Mon Sep 17 00:00:00 2001 From: rickylabs <129366361+rickylabs@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:46:07 +0100 Subject: [PATCH 4/5] test(cli): retain documented database command evidence Observe the original awaited command at the walkthrough call site and reuse the safe flat artifact collector without changing execution or cleanup. Refs #2648 --- .../evidence/database-generate-diagnostic.ts | 71 ++++++++--- .../database-generate-diagnostic_test.ts | 112 ++++++++++++++++++ .../scaffold/verify-documented-scaffold.ts | 92 ++++++++++---- 3 files changed, 241 insertions(+), 34 deletions(-) diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts index ed7cbeba6a..1eda0ed653 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts @@ -26,25 +26,68 @@ export function databaseGenerateEvidence( }, ) => Promise = save, ): (observation: CommandObservation) => Promise { - return async ({ context, result, startedAt, completedAt }) => { - const appHost = context.project.appHost; - await collect({ + return ({ context, result, startedAt, completedAt }) => + collectDatabaseGenerateExecution({ projectRoot: context.project.projectRoot, - appHost, + appHost: context.project.appHost, runnerRoot: context.project.repoRoot, - invocation: { + result, + startedAt, + completedAt, + }, collect); +} + +/** Evidence from a direct documented command, using the same safe owning collector. */ +export function collectDatabaseGenerateExecution(input: { + readonly projectRoot: string; + readonly appHost: string; + readonly runnerRoot: string; + readonly result: Pick; + readonly startedAt: string; + readonly completedAt: string; +}, collect: Parameters[0] = save): Promise { + return collect({ + projectRoot: input.projectRoot, + appHost: input.appHost, + runnerRoot: input.runnerRoot, + invocation: { + ...input.result, + startedAt: input.startedAt, + completedAt: input.completedAt, + process: 'database_cli', + reportedRestart: reportedRestartFailure( + input.result.stderr + '\n' + input.result.stdout, + input.appHost, + ), + }, + }); +} + +/** Select only the actual documented database-generation command, before native execution. */ +export function documentedDatabaseGenerateEvidence( + words: readonly string[], + scope: { readonly projectRoot: string; readonly appHost: string; readonly runnerRoot: string }, + collect?: Parameters[0], +): + | (( + output: { result: Deno.CommandOutput; startedAt: string; completedAt: string }, + ) => Promise) + | undefined { + if (words[0] !== 'netscript' || words[1] !== 'db' || words[2] !== 'generate') return undefined; + return ({ result, startedAt, completedAt }) => + collectDatabaseGenerateExecution({ + ...scope, + startedAt, + completedAt, + result: { code: result.code, - stdout: result.stdout, - stderr: result.stderr, - startedAt, - completedAt, - process: 'database_cli', - timedOut: result.timedOut, - reportedRestart: reportedRestartFailure(result.stderr + '\n' + result.stdout, appHost), + stdout: new TextDecoder().decode(result.stdout), + stderr: new TextDecoder().decode(result.stderr), + timedOut: false, }, - }); - }; + }, collect); } + async function save( input: { readonly projectRoot: string; diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts index 0045c2e8d9..b4a57be67b 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts @@ -1,6 +1,8 @@ +import { documentedScaffoldCommand } from '../../verify-documented-scaffold.ts'; import { assert, assertEquals } from '@std/assert'; import { databaseGenerateEvidence, + documentedDatabaseGenerateEvidence, reportedRestartFailure, } from './database-generate-diagnostic.ts'; import { CommandGate } from '../../../command-gate.ts'; @@ -115,3 +117,113 @@ Deno.test('nested restart result requires the exact reported target and never be assertEquals(reportedRestartFailure(failure, '/foreign/apphost.mts'), undefined); assertEquals(reportedRestartFailure(failure.replace('exit 16', 'exit 999'), appHost), undefined); }); + +Deno.test('documented database command observes original native output without replacing failure or running another child', async () => { + const scope = { projectRoot: context.project.projectRoot, appHost, runnerRoot: '/repo' }; + let calls = 0, collections = 0, settled = false; + const words = ['netscript', 'db', 'generate']; + const args = ['run', '-A', '/repo/cli.ts', ...words.slice(1)]; + const collect: Parameters[2] = (input) => { + assert(settled); + collections++; + assertEquals(input.projectRoot, scope.projectRoot); + assertEquals(input.runnerRoot, '/repo'); + assertEquals(input.invocation.code, 1); + assertEquals(input.invocation.reportedRestart, { resource: 'web', exit: 16 }); + return Promise.reject(new Error('SECRET_DIAGNOSTIC_FAILURE')); + }; + let failure: unknown; + try { + await documentedScaffoldCommand(words, words.slice(1), { + ...scope, + cwd: scope.projectRoot, + cliEntrypoint: '/repo/cli.ts', + repoRoot: '/repo', + }, { + collect, + execute: (program, options) => { + calls++; + assertEquals(program, Deno.execPath()); + assertEquals(options.args, args); + assertEquals(options.cwd, scope.projectRoot); + assertEquals(options.stdin, 'null'); + assertEquals(options.stdout, 'piped'); + assertEquals(options.stderr, 'piped'); + assert(options.signal); + settled = true; + return Promise.resolve({ + code: 1, + signal: null, + success: false, + stdout: new TextEncoder().encode('original stdout'), + stderr: new TextEncoder().encode(failureText), + }); + }, + }); + } catch (error) { + failure = error; + } + assert(failure instanceof Error); + assertEquals( + failure.message, + `${Deno.execPath()} ${args.join(' ')} exited 1: ${failureText}\noriginal stdout`, + ); + assertEquals(calls, 1); + assertEquals(collections, 1); + for ( + const other of [['netscript', 'db', 'seed'], ['aspire', 'start'], ['deno', 'db', 'generate']] + ) { + assertEquals(documentedDatabaseGenerateEvidence(other, scope), undefined); + } +}); +const failureText = failure; + +Deno.test('documented command keeps successful output and original native rejection when diagnostics are unavailable', async () => { + const words = ['netscript', 'db', 'generate']; + const input = { + cwd: '/repo/run/app', + projectRoot: '/repo/run/app', + appHost, + repoRoot: '/repo', + cliEntrypoint: '/repo/cli.ts', + }; + let calls = 0, collections = 0; + const success = await documentedScaffoldCommand(words, words.slice(1), input, { + execute: () => { + calls++; + return Promise.resolve({ + code: 0, + signal: null, + success: true, + stdout: new TextEncoder().encode('original success'), + stderr: new Uint8Array(), + }); + }, + collect: () => { + collections++; + return Promise.reject(new Error('SECRET_COLLECTOR')); + }, + }); + assertEquals(success, 'original success'); + assertEquals(calls, 1); + assertEquals(collections, 1); + const original = new Error('fixture_native_rejection'); + let caught: unknown; + try { + await documentedScaffoldCommand(words, words.slice(1), input, { + execute: () => { + calls++; + return Promise.reject(original); + }, + collect: () => { + collections++; + return Promise.resolve(); + }, + }); + } catch (error) { + caught = error; + } + assertEquals(caught, original); + assertEquals(calls, 2); + assertEquals(collections, 1); +}); diff --git a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts index 22f02319ef..35ffa76a7c 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts @@ -1,5 +1,6 @@ /** Execute the documented scaffold order without the main suite's repair fixtures. @module */ import { join, resolve } from '@std/path'; +import { documentedDatabaseGenerateEvidence } from './runtime/evidence/database-generate-diagnostic.ts'; import { buildStreamUrl } from '@netscript/plugin-streams-core'; import { z } from 'zod'; import { @@ -26,14 +27,27 @@ type Outcome = { readonly passed: true; readonly id: string } | { readonly error: unknown; }; -async function command(executable: string, args: readonly string[], cwd: string): Promise { +/** Original direct native command; evidence is observed only after its output settles. */ +export async function documentedCommand( + executable: string, + args: readonly string[], + cwd: string, + afterCommand?: ( + output: { result: Deno.CommandOutput; startedAt: string; completedAt: string }, + ) => Promise, + execute: (executable: string, options: Deno.CommandOptions) => Promise = ( + program, + options, + ) => new Deno.Command(program, options).output(), +): Promise { const startingAspire = executable === 'aspire' && args[0] === 'start'; const startTimeout = Deno.env.get('ASPIRE_CLI_START_TIMEOUT') ?? String(DEFAULT_ASPIRE_START_TIMEOUT_SECONDS); const ceiling = startingAspire ? Math.max(COMMAND_CEILING_MS, (Number(startTimeout) + 30) * 1_000) : COMMAND_CEILING_MS; - const result = await new Deno.Command(executable, { + const startedAt = new Date().toISOString(); + const result = await execute(executable, { args: [...args], cwd, stdin: 'null', @@ -41,7 +55,14 @@ async function command(executable: string, args: readonly string[], cwd: string) stderr: 'piped', signal: AbortSignal.timeout(ceiling), ...(startingAspire ? { env: { ASPIRE_CLI_START_TIMEOUT: startTimeout } } : {}), - }).output(); + }); + if (afterCommand) { + try { + await afterCommand({ result, startedAt, completedAt: new Date().toISOString() }); + } catch { + console.warn('Documented command diagnostic collection unavailable'); + } + } const stdout = new TextDecoder().decode(result.stdout); if (!result.success) { throw new Error( @@ -53,6 +74,45 @@ async function command(executable: string, args: readonly string[], cwd: string) return stdout; } +/** The actual walkthrough call site, shared with inert command-boundary controls. */ +export function documentedScaffoldCommand( + words: readonly string[], + args: readonly string[], + input: { + cwd: string; + cliEntrypoint: string; + projectRoot: string; + appHost: string; + repoRoot: string; + }, + seams: { + execute?: Parameters[4]; + collect?: Parameters[2]; + } = {}, +): Promise { + return documentedCommand( + words[0] === 'netscript' ? Deno.execPath() : 'aspire', + words[0] === 'netscript' + ? [ + 'run', + '-A', + ...(input.cliEntrypoint.startsWith('jsr:@netscript/cli@') + ? ['--minimum-dependency-age=0'] + : []), + input.cliEntrypoint, + ...args, + ] + : args, + input.cwd, + documentedDatabaseGenerateEvidence(words, { + projectRoot: input.projectRoot, + appHost: input.appHost, + runnerRoot: input.repoRoot, + }, seams.collect), + seams.execute, + ); +} + async function responseJson(url: string | URL): Promise { const response = await fetch(url, { signal: AbortSignal.timeout(10_000) }); if (!response.ok) { @@ -120,7 +180,7 @@ async function workerPid(appHost: string, cwd: string): Promise { properties: z.record(z.string(), z.unknown()), })), }).parse(JSON.parse( - await command('aspire', [ + await documentedCommand('aspire', [ 'describe', '--apphost', appHost, @@ -140,7 +200,7 @@ async function workerPid(appHost: string, cwd: string): Promise { async function cleanup(repoRoot: string, projectRoot: string): Promise { const receiptPath = join(projectRoot, '.netscript/e2e-cleanup.json'); - await command(Deno.execPath(), [ + await documentedCommand(Deno.execPath(), [ 'run', '--allow-read', '--allow-write', @@ -220,7 +280,7 @@ async function runVariant( await Deno.writeTextFile(runtime, broken); } if (words[0] === 'netscript' && args[0] === 'db' && args[1] === 'seed') { - await command('aspire', [ + await documentedCommand('aspire', [ 'wait', 'workers', '--status', @@ -235,21 +295,13 @@ async function runVariant( beforeSeedPid = await workerPid(appHost, cwd); } if (words[0] === 'aspire' && args[0] === 'start') appHostStarted = true; - await command( - words[0] === 'netscript' ? Deno.execPath() : 'aspire', - words[0] === 'netscript' - ? [ - 'run', - '-A', - ...(cliEntrypoint.startsWith('jsr:@netscript/cli@') - ? ['--minimum-dependency-age=0'] - : []), - cliEntrypoint, - ...args, - ] - : args, + await documentedScaffoldCommand(words, args, { cwd, - ); + cliEntrypoint, + projectRoot, + appHost, + repoRoot, + }); } const seed = await outcome(() => seedExecution(appHost, projectRoot)); const stream = await outcome(() => activity(appHost, projectRoot)); From b804381066ea7c519ca151b90fbc6dec35f1161e Mon Sep 17 00:00:00 2001 From: rickylabs <129366361+rickylabs@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:25:54 +0100 Subject: [PATCH 5/5] test(cli): bind restart evidence to scope and settlement state Use the canonical log root and declared generated consumer names. Filter linked host evidence to the command interval and retain actual cancellation state without changing lifecycle calls, budgets or failure propagation. Refs #2648 --- .../adapters/commands/deno-command-adapter.ts | 37 +++-- .../e2e/src/application/gates/command-gate.ts | 1 + .../evidence/database-generate-diagnostic.ts | 41 +++-- .../database-generate-diagnostic_test.ts | 46 ++++++ .../runtime/evidence/invocation-diagnostic.ts | 116 ++++++++++++-- .../evidence/invocation-diagnostic_test.ts | 144 +++++++++++++++++- .../evidence/owned-invocation-diagnostic.ts | 2 +- .../scaffold/verify-documented-scaffold.ts | 23 ++- .../cli/e2e/src/ports/command-executor.ts | 7 + .../commands/deno-command-adapter_test.ts | 61 ++++++++ 10 files changed, 441 insertions(+), 37 deletions(-) create mode 100644 packages/cli/e2e/tests/adapters/commands/deno-command-adapter_test.ts diff --git a/packages/cli/e2e/src/adapters/commands/deno-command-adapter.ts b/packages/cli/e2e/src/adapters/commands/deno-command-adapter.ts index 8a782677ee..2ae73e41d3 100644 --- a/packages/cli/e2e/src/adapters/commands/deno-command-adapter.ts +++ b/packages/cli/e2e/src/adapters/commands/deno-command-adapter.ts @@ -8,22 +8,36 @@ const decoder = new TextDecoder(); /** Deno.Command-backed process adapter. */ export class DenoCommandAdapter implements CommandExecutor { + constructor( + private readonly native: { + capture(command: string, options: Deno.CommandOptions): Promise; + status(command: string, options: Deno.CommandOptions): Promise; + } = { + capture: (command, options) => new Deno.Command(command, options).output(), + status: (command, options) => new Deno.Command(command, options).spawn().status, + }, + ) {} async run(request: CommandRequest): Promise { const controller = new AbortController(); + let deadlineExpired = false; + const settlementSignal = () => ({ abortRequested: controller.signal.aborted, deadlineExpired }); const timeout = request.timeoutMs - ? setTimeout(() => controller.abort(), request.timeoutMs) + ? setTimeout(() => { + deadlineExpired = true; + controller.abort(); + }, request.timeoutMs) : undefined; try { const [command, ...args] = request.command; if (request.outputMode === 'discard') { - const child = new Deno.Command(command, { + const status = await this.native.status(command, { args, cwd: request.cwd, stdout: 'null', stderr: 'null', signal: controller.signal, - }).spawn(); - const status = await child.status; + }); + const signalAtSettlement = settlementSignal(); return { command: request.command, cwd: request.cwd, @@ -31,27 +45,31 @@ export class DenoCommandAdapter implements CommandExecutor { stdout: '', stderr: status.code === 0 ? '' : request.failureHint ?? 'Command failed while output capture was disabled. Re-run the command directly to inspect its output.', - timedOut: false, + timedOut: signalAtSettlement.deadlineExpired, + signalAtSettlement, }; } - const output = await new Deno.Command(command, { + const output = await this.native.capture(command, { args, cwd: request.cwd, stdout: 'piped', stderr: 'piped', signal: controller.signal, - }).output(); + }); + const signalAtSettlement = settlementSignal(); return { command: request.command, cwd: request.cwd, code: output.code, stdout: decoder.decode(output.stdout), stderr: decoder.decode(output.stderr), - timedOut: false, + timedOut: signalAtSettlement.deadlineExpired, + signalAtSettlement, }; } catch (error) { - const timedOut = error instanceof DOMException && error.name === 'AbortError'; + const signalAtSettlement = settlementSignal(); + const timedOut = signalAtSettlement.deadlineExpired; return { command: request.command, cwd: request.cwd, @@ -59,6 +77,7 @@ export class DenoCommandAdapter implements CommandExecutor { stdout: '', stderr: timedOut ? 'Command timed out.' : String(error), timedOut, + signalAtSettlement, }; } finally { if (timeout) clearTimeout(timeout); diff --git a/packages/cli/e2e/src/application/gates/command-gate.ts b/packages/cli/e2e/src/application/gates/command-gate.ts index e36b99bb2b..f8ca861980 100644 --- a/packages/cli/e2e/src/application/gates/command-gate.ts +++ b/packages/cli/e2e/src/application/gates/command-gate.ts @@ -77,6 +77,7 @@ export class CommandGate { cwd: result.cwd, code: result.code, timedOut: result.timedOut, + signalAtSettlement: result.signalAtSettlement ?? null, stdoutTail: tail(result.stdout), stderrTail: tail(result.stderr), }, diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts index 1eda0ed653..485ec90f66 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic.ts @@ -1,15 +1,21 @@ +import type { CommandSignalAtSettlement } from '../../../../../ports/command-executor.ts'; import type { CommandObservation } from '../../../../../domain/gate-definition.ts'; /** Test-only evidence around the original database.generate command; no additional Aspire calls. */ import { saveOwnedInvocationDiagnostics } from './owned-invocation-diagnostic.ts'; -import type { CapturedInvocation } from './invocation-diagnostic.ts'; +import { type CapturedInvocation, diagnosticResourceName } from './invocation-diagnostic.ts'; +import { generatedAppName } from '../generated-app-name.ts'; /** The nested Aspire exit is reported by the CLI, distinct from the captured database CLI exit. */ -export function reportedRestartFailure(text: string, appHost: string) { +export function reportedRestartFailure( + text: string, + appHost: string, + scoped: readonly string[] = [], +) { const match = - /Database client generated, but (web|api|workers|postgres|redis|garnet|streams|dashboard) restart failed \(Aspire exit ([0-9]{1,3})\)\./ + /Database client generated, but ([a-z][a-z0-9-]{0,127}) restart failed \(Aspire exit ([0-9]{1,3})\)\./ .exec(text); if ( - !match || Number(match[2]) > 255 || + !match || diagnosticResourceName(match[1], scoped) === null || Number(match[2]) > 255 || !text.includes(`Run: aspire resource ${match[1]} restart --apphost ${JSON.stringify(appHost)}`) ) return undefined; return { resource: match[1], exit: Number(match[2]) }; @@ -32,6 +38,7 @@ export function databaseGenerateEvidence( appHost: context.project.appHost, runnerRoot: context.project.repoRoot, result, + scopedResources: ['users', generatedAppName(context)], startedAt, completedAt, }, collect); @@ -42,7 +49,11 @@ export function collectDatabaseGenerateExecution(input: { readonly projectRoot: string; readonly appHost: string; readonly runnerRoot: string; - readonly result: Pick; + readonly result: Pick< + CommandObservation['result'], + 'code' | 'stdout' | 'stderr' | 'timedOut' | 'signalAtSettlement' + >; + readonly scopedResources?: readonly string[]; readonly startedAt: string; readonly completedAt: string; }, collect: Parameters[0] = save): Promise { @@ -51,13 +62,19 @@ export function collectDatabaseGenerateExecution(input: { appHost: input.appHost, runnerRoot: input.runnerRoot, invocation: { - ...input.result, + code: input.result.code, + stdout: input.result.stdout, + stderr: input.result.stderr, + timedOut: input.result.timedOut, + signalAtSettlement: input.result.signalAtSettlement, + scopedResources: input.scopedResources, startedAt: input.startedAt, completedAt: input.completedAt, process: 'database_cli', reportedRestart: reportedRestartFailure( input.result.stderr + '\n' + input.result.stdout, input.appHost, + input.scopedResources, ), }, }); @@ -70,11 +87,16 @@ export function documentedDatabaseGenerateEvidence( collect?: Parameters[0], ): | (( - output: { result: Deno.CommandOutput; startedAt: string; completedAt: string }, + output: { + result: Deno.CommandOutput; + startedAt: string; + completedAt: string; + signalAtSettlement: CommandSignalAtSettlement; + }, ) => Promise) | undefined { if (words[0] !== 'netscript' || words[1] !== 'db' || words[2] !== 'generate') return undefined; - return ({ result, startedAt, completedAt }) => + return ({ result, startedAt, completedAt, signalAtSettlement }) => collectDatabaseGenerateExecution({ ...scope, startedAt, @@ -83,7 +105,8 @@ export function documentedDatabaseGenerateEvidence( code: result.code, stdout: new TextDecoder().decode(result.stdout), stderr: new TextDecoder().decode(result.stderr), - timedOut: false, + timedOut: signalAtSettlement.deadlineExpired, + signalAtSettlement, }, }, collect); } diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts index b4a57be67b..71518c0eb6 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/database-generate-diagnostic_test.ts @@ -227,3 +227,49 @@ Deno.test('documented command keeps successful output and original native reject assertEquals(calls, 2); assertEquals(collections, 1); }); + +Deno.test('database evidence binds a generated consumer name to the actual run scope', async () => { + const scoped: RunContext = { + ...context, + request: { + ...context.request, + options: { ...context.request.options, projectName: 'synthetic-smoke' }, + }, + }; + const name = 'synthetic-smoke-web'; + const text = + `Database client generated, but ${name} restart failed (Aspire exit 16).\nRun: aspire resource ${name} restart --apphost ${ + JSON.stringify(appHost) + }`; + let reported: unknown; + await databaseGenerateEvidence((input) => { + reported = input.invocation.reportedRestart; + return Promise.resolve(); + })({ + context: scoped, + result: { command: ['deno'], cwd: '/repo', code: 1, stdout: '', stderr: text, timedOut: false }, + startedAt: '2026-01-01T23:01:18.000Z', + completedAt: '2026-01-01T23:01:47.000Z', + }); + assertEquals(reported, { resource: name, exit: 16 }); +}); + +Deno.test('generated restart reporting refuses foreign names or another host even with an apparently valid remedy', () => { + const scoped = ['synthetic-smoke-web']; + const text = (name: string, host: string) => + `Database client generated, but ${name} restart failed (Aspire exit 16).\nRun: aspire resource ${name} restart --apphost ${ + JSON.stringify(host) + }`; + assertEquals(reportedRestartFailure(text('synthetic-smoke-web', appHost), appHost, scoped), { + resource: 'synthetic-smoke-web', + exit: 16, + }); + assertEquals( + reportedRestartFailure(text('foreign-smoke-web', appHost), appHost, scoped), + undefined, + ); + assertEquals( + reportedRestartFailure(text('synthetic-smoke-web', '/foreign/apphost.mts'), appHost, scoped), + undefined, + ); +}); diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts index 14885ed996..a6b3f0fce7 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic.ts @@ -25,18 +25,82 @@ export interface CapturedInvocation { readonly process?: 'aspire' | 'database_cli'; readonly timedOut?: boolean; readonly reportedRestart?: { readonly resource: string; readonly exit: number }; + /** Trusted fixture scope, never taken from command output. */ + readonly scopedResources?: readonly string[]; + readonly signalAtSettlement?: { + readonly abortRequested: boolean; + readonly deadlineExpired: boolean; + }; } export interface DiagnosticRecord { readonly resourceKind: string | null; readonly resourceName: string | null; readonly errorCode: string | null; + readonly stopState?: 'requested' | 'not_terminal' | 'confirmed'; +} +/** Names beyond the fixed vocabulary require an exact server-owned run binding. */ +export function diagnosticResourceName( + name: unknown, + scoped: readonly string[] = [], +): string | null { + if (typeof name !== 'string') return null; + if (NAMES.has(name)) return name; + return scoped.length <= 16 && scoped.includes(name) && /^[a-z][a-z0-9-]{0,127}$/.test(name) + ? name + : null; +} +function recordTime(row: Record | null): number | null { + const value = row?.Timestamp ?? row?.timestamp ?? row?.['@t']; + if (typeof value !== 'string') return null; + const at = Date.parse(value); + return Number.isFinite(at) ? at : null; +} + +function withinInvocation(at: number | null, invocation: CapturedInvocation): boolean { + const start = Date.parse(invocation.startedAt ?? ''), + end = Date.parse(invocation.completedAt ?? ''); + return at !== null && Number.isFinite(at) && Number.isFinite(start) && Number.isFinite(end) && + end >= start && at >= start && at <= end; +} + +/** Pinned CLI file-log prefix and closed DcpExecutor templates; no free-form message is retained. */ +function scopedStopRecord( + line: string, + scoped: readonly string[], + window?: CapturedInvocation, +): DiagnosticRecord | null { + const prefix = + /^\[(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}\.\d{3})\] \[[A-Z]{3,5}\] \[(?:AppHost|DcpExecutor|Aspire\.Hosting\.Dcp\.DcpExecutor)\] (.+)$/ + .exec(line); + if (!prefix) return null; + const at = Date.parse(prefix[1] + 'T' + prefix[2] + 'Z'); + if (!Number.isFinite(at) || window && !withinInvocation(at, window)) return null; + const match = + /^(?:Stopping resource '([^']+)'\.\.\.|Executable '([^']+)' (was stopped\.|is still running; trying again to stop it\.\.\.))$/ + .exec(prefix[3]); + if (!match) return null; + const physical = match[1] ?? match[2]; + const candidates = [...NAMES, ...scoped.slice(0, 16)]; + const logical = candidates.find((name) => + diagnosticResourceName(name, scoped) !== null && + (physical === name || + physical.startsWith(name + '-') && /^[a-z0-9]{8}$/.test(physical.slice(name.length + 1))) + ); + if (!logical) return null; + return { + resourceKind: 'executable', + resourceName: logical, + errorCode: null, + stopState: match[1] ? 'requested' : match[3] === 'was stopped.' ? 'confirmed' : 'not_terminal', + }; } + function object(value: unknown): Record | null { return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record : null; } -function records(text: string) { +function records(text: string, scoped: readonly string[] = [], window?: CapturedInvocation) { const result: DiagnosticRecord[] = []; let ignored = 0; for (const line of text.split(/\r?\n/)) { @@ -45,13 +109,27 @@ function records(text: string) { try { row = object(JSON.parse(line)); } catch { /* Free-form text never crosses this boundary. */ } + if (!row) { + const stop = scopedStopRecord(line, scoped, window); + if (stop && result.length < 16) { + result.push(stop); + continue; + } + } + if (window) { + const at = recordTime(row); + if (!withinInvocation(at, window)) { + ignored++; + continue; + } + } const properties = object(row?.Properties) ?? row; const kind = properties?.resourceKind ?? properties?.ResourceKind; const name = properties?.resourceName ?? properties?.ResourceName; const error = properties?.errorCode ?? properties?.ErrorCode; const value = { resourceKind: typeof kind === 'string' && KINDS.has(kind) ? kind : null, - resourceName: typeof name === 'string' && NAMES.has(name) ? name : null, + resourceName: diagnosticResourceName(name, scoped), errorCode: typeof error === 'string' && ERRORS.has(error) ? error : null, }; if (Object.values(value).some((v) => v !== null) && result.length < 16) result.push(value); @@ -65,7 +143,7 @@ async function sha(bytes: Uint8Array): Promise { return [...new Uint8Array(await crypto.subtle.digest('SHA-256', copy))] .map((byte) => byte.toString(16).padStart(2, '0')).join(''); } -async function textEvidence(text: string) { +async function textEvidence(text: string, scoped: readonly string[] = []) { const tail = text.slice(-MAX_BYTES); const encoded = new TextEncoder().encode(tail); const bytes = encoded.slice(-MAX_BYTES); @@ -75,7 +153,7 @@ async function textEvidence(text: string) { readBytes: bytes.length, truncated, capturedSha256: await sha(bytes), - ...records(new TextDecoder().decode(bytes)), + ...records(new TextDecoder().decode(bytes), scoped), }; } function logReferences(text: string): string[] { @@ -124,11 +202,15 @@ export async function selectedInvocationLog( ) { const name = basename(path), match = CLI_LOG.exec(name); const start = secondStamp(invocation.startedAt), end = secondStamp(invocation.completedAt); - if ( - !isAbsolute(path) || !inside(resolve(path), resolve(root)) || - !(appHost ? APPHOST_LOG.test(name) : match !== null) || - (!appHost && (!start || !end || match![1] < start || match![1] > end)) - ) return { status: 'refused' as const }; + if (!isAbsolute(path) || !inside(resolve(path), resolve(root))) { + return { status: 'refused' as const, reason: 'outside_log_scope' as const }; + } + if (!(appHost ? APPHOST_LOG.test(name) : match !== null)) { + return { status: 'refused' as const, reason: 'filename_unproven' as const }; + } + if (!appHost && (!start || !end || match![1] < start || match![1] > end)) { + return { status: 'refused' as const, reason: 'outside_invocation_window' as const }; + } try { const before = await Deno.lstat(path); if ( @@ -164,7 +246,7 @@ export async function selectedInvocationLog( readBytes: size, truncated: opened.size > size, capturedSha256: await sha(bytes), - ...records(text), + ...records(text, invocation.scopedResources, appHost ? invocation : undefined), linkedAppHost: appHost ? [] : logReferences(text).filter((value) => APPHOST_LOG.test(basename(value))).slice(0, 2), @@ -216,15 +298,23 @@ export async function invocationDiagnostic(input: { nativeExit: invocation.process === 'database_cli' ? null : invocation.code, executorExit: invocation.process === 'database_cli' ? invocation.code : null, timedOut: invocation.timedOut ?? false, + signalAtSettlement: invocation.signalAtSettlement + ? { + abortRequested: invocation.signalAtSettlement.abortRequested, + deadlineExpired: invocation.signalAtSettlement.deadlineExpired, + } + : null, process: invocation.process ?? 'aspire', - reportedRestart: invocation.reportedRestart && NAMES.has(invocation.reportedRestart.resource) && + reportedRestart: invocation.reportedRestart && + diagnosticResourceName(invocation.reportedRestart.resource, invocation.scopedResources) !== + null && Number.isInteger(invocation.reportedRestart.exit) && invocation.reportedRestart.exit >= 0 && invocation.reportedRestart.exit <= 255 ? { resource: invocation.reportedRestart.resource, exit: invocation.reportedRestart.exit } : null, targetMatches: input.targetMatches, - stdout: await textEvidence(invocation.stdout), - stderr: await textEvidence(invocation.stderr), + stdout: await textEvidence(invocation.stdout, invocation.scopedResources), + stderr: await textEvidence(invocation.stderr, invocation.scopedResources), log: safeLog, linkedState: linked.length === 0 ? 'missing_reference' diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts index 7109144d86..6b02ad3549 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/invocation-diagnostic_test.ts @@ -21,14 +21,17 @@ const safeDetail = JSON.stringify({ Deno.test('both output streams retain only safe details; exact linked logs are bounded and private', async () => { const root = await Deno.makeTempDir(); try { - const home = join(root, 'home'), logs = join(home, '.aspire', 'cli', 'logs'); + const home = join(root, 'home'), logs = join(home, '.aspire', 'logs'); await Deno.mkdir(logs, { recursive: true }); await Deno.mkdir(join(root, '.netscript')); const uid = (await Deno.stat(root)).uid; if (uid === null) throw new Error('fixture requires filesystem UID'); const log = join(logs, 'cli_20260101T000001_deadbeef.log'); const app = join(logs, 'cli_20260101T000000000_detach-child_deadbeef.log'); - await Deno.writeTextFile(app, safeDetail); + await Deno.writeTextFile( + app, + JSON.stringify({ ...JSON.parse(safeDetail), Timestamp: '2026-01-01T00:00:01.000Z' }), + ); await Deno.writeTextFile(log, safeDetail + '\n' + app + '\nSECRET_LOG_SENTINEL'); const invocation = { ...times, @@ -205,3 +208,140 @@ Deno.test('actual stop-and-probe retains nonzero outcome and exact command count await Deno.remove(root, { recursive: true }); } }); + +Deno.test('owned restart evidence reads only the canonical command log and invocation-scoped records from its older linked host log', async () => { + const root = await Deno.makeTempDir(); + try { + const home = join(root, 'home'), logs = join(home, '.aspire', 'logs'); + await Deno.mkdir(logs, { recursive: true }); + await Deno.mkdir(join(root, '.netscript')); + const uid = (await Deno.stat(root)).uid; + assert(uid !== null); + const log = join(logs, 'cli_20260101T230130_deadbeef.log'); + const app = join(logs, 'cli_20260101T230011987_detach-child_deadbeef.log'); + const detail = (at: string) => + JSON.stringify({ + Timestamp: at, + resourceKind: 'executable', + resourceName: 'synthetic-smoke-web', + errorCode: 'in_use', + Config: { Env: ['SECRET_ENV_SENTINEL'] }, + }); + await Deno.writeTextFile( + app, + detail('2026-01-01T23:00:12.000Z') + '\n' + detail('2026-01-01T23:01:35.000Z'), + ); + await Deno.writeTextFile(log, app + '\n' + detail('2026-01-01T23:01:36.000Z')); + const invocation = { + code: 1, + process: 'database_cli' as const, + timedOut: false, + scopedResources: ['synthetic-smoke-web'], + reportedRestart: { resource: 'synthetic-smoke-web', exit: 16 }, + startedAt: '2026-01-01T23:01:18.000Z', + completedAt: '2026-01-01T23:01:47.000Z', + stdout: '', + stderr: log, + }; + await saveOwnedInvocationDiagnostics({ + projectRoot: root, + appHost: join(root, 'apphost.mts'), + kind: 'restart', + home, + uid, + transcripts: [invocation], + }); + const result = JSON.parse( + await Deno.readTextFile(join(root, '.netscript/e2e-restart-diagnostic.json')), + ); + const record = result.commands[0]; + assertEquals(record.log.status, 'available'); + assertEquals(record.reportedRestart, { resource: 'synthetic-smoke-web', exit: 16 }); + assertEquals(record.nativeExit, null); + assertEquals(record.executorExit, 1); + assertEquals(record.linkedLog.status, 'available'); + assertEquals( + record.linkedLog.records.length, + 1, + 'older host records must not become current-invocation evidence', + ); + assertEquals(record.linkedLog.ignoredLines, 1); + assert(!JSON.stringify(result).includes('SECRET_')); + assert(!JSON.stringify(result).includes(home)); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); + +Deno.test('linked host evidence admits only in-window closed stop templates and preserves unknown linkage', async () => { + const root = await Deno.makeTempDir(); + try { + const uid = (await Deno.stat(root)).uid; + assert(uid !== null); + const log = join(root, 'cli_20260101T230130_deadbeef.log'); + const app = join(root, 'cli_20260101T230011987_detach-child_deadbeef.log'); + const line = (at: string, name: string) => + `[2026-01-01 ${at}] [DBG] [DcpExecutor] Executable '${name}-abcdefgh' is still running; trying again to stop it...`; + await Deno.writeTextFile(log, app); + await Deno.writeTextFile( + app, + [ + line('23:00:12.000', 'synthetic-smoke-web'), + line('23:01:35.000', 'synthetic-smoke-web'), + line('23:01:36.000', 'foreign-web'), + 'SECRET_ENV_SENTINEL', + 'Executable without a clock was stopped.', + ].join('\n'), + ); + const invocation = { + code: 1, + stdout: '', + stderr: log, + process: 'database_cli' as const, + scopedResources: ['synthetic-smoke-web'], + startedAt: '2026-01-01T23:01:18.000Z', + completedAt: '2026-01-01T23:01:47.000Z', + timedOut: false, + signalAtSettlement: { abortRequested: false, deadlineExpired: false }, + }; + const result = await invocationDiagnostic({ + invocation, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: true, + }); + assert(result.linkedLog && 'records' in result.linkedLog); + assertEquals(result.linkedLog.records, [{ + resourceKind: 'executable', + resourceName: 'synthetic-smoke-web', + errorCode: null, + stopState: 'not_terminal', + }]); + assertEquals(result.signalAtSettlement, { abortRequested: false, deadlineExpired: false }); + assertEquals(result.timedOut, false); + assertEquals(result.nativeExit, null); + assert(!JSON.stringify(result).includes('SECRET_')); + await Deno.writeTextFile(log, 'no proved linked host reference'); + const unlinked = await invocationDiagnostic({ + invocation, + logRoot: root, + uid, + ordinal: 1, + operation: 'restart', + targetMatches: true, + }); + assertEquals(unlinked.linkedLog, null); + assertEquals(unlinked.linkedState, 'missing_reference'); + const outside = await selectedInvocationLog( + join(root, 'cli_20260101T230010_deadbeef.log'), + root, + invocation, + uid, + ); + assertEquals(outside, { status: 'refused', reason: 'outside_invocation_window' }); + } finally { + await Deno.remove(root, { recursive: true }); + } +}); diff --git a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts index 9770d175ff..80aff2ead7 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/runtime/evidence/owned-invocation-diagnostic.ts @@ -103,7 +103,7 @@ export async function saveOwnedInvocationDiagnostics(input: { ordinal: index + 1, operation: kind === 'cleanup' ? 'stop' : 'restart', targetMatches, - logRoot: join(input.home, '.aspire', 'cli', 'logs'), + logRoot: join(input.home, '.aspire', 'logs'), uid: input.uid, }), ); diff --git a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts index 35ffa76a7c..fe548da3ba 100644 --- a/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts +++ b/packages/cli/e2e/src/application/gates/scaffold/verify-documented-scaffold.ts @@ -1,5 +1,6 @@ /** Execute the documented scaffold order without the main suite's repair fixtures. @module */ import { join, resolve } from '@std/path'; +import type { CommandSignalAtSettlement } from '../../../ports/command-executor.ts'; import { documentedDatabaseGenerateEvidence } from './runtime/evidence/database-generate-diagnostic.ts'; import { buildStreamUrl } from '@netscript/plugin-streams-core'; import { z } from 'zod'; @@ -33,7 +34,12 @@ export async function documentedCommand( args: readonly string[], cwd: string, afterCommand?: ( - output: { result: Deno.CommandOutput; startedAt: string; completedAt: string }, + output: { + result: Deno.CommandOutput; + startedAt: string; + completedAt: string; + signalAtSettlement: CommandSignalAtSettlement; + }, ) => Promise, execute: (executable: string, options: Deno.CommandOptions) => Promise = ( program, @@ -47,18 +53,29 @@ export async function documentedCommand( ? Math.max(COMMAND_CEILING_MS, (Number(startTimeout) + 30) * 1_000) : COMMAND_CEILING_MS; const startedAt = new Date().toISOString(); + const commandSignal = AbortSignal.timeout(ceiling); const result = await execute(executable, { args: [...args], cwd, stdin: 'null', stdout: 'piped', stderr: 'piped', - signal: AbortSignal.timeout(ceiling), + signal: commandSignal, ...(startingAspire ? { env: { ASPIRE_CLI_START_TIMEOUT: startTimeout } } : {}), }); + const signalAtSettlement = { + abortRequested: commandSignal.aborted, + deadlineExpired: commandSignal.aborted && commandSignal.reason instanceof DOMException && + commandSignal.reason.name === 'TimeoutError', + }; if (afterCommand) { try { - await afterCommand({ result, startedAt, completedAt: new Date().toISOString() }); + await afterCommand({ + result, + startedAt, + completedAt: new Date().toISOString(), + signalAtSettlement, + }); } catch { console.warn('Documented command diagnostic collection unavailable'); } diff --git a/packages/cli/e2e/src/ports/command-executor.ts b/packages/cli/e2e/src/ports/command-executor.ts index a7290cc023..9f8f92172a 100644 --- a/packages/cli/e2e/src/ports/command-executor.ts +++ b/packages/cli/e2e/src/ports/command-executor.ts @@ -10,6 +10,12 @@ export interface CommandRequest { readonly failureHint?: string; } +/** Actual existing cancellation state, sampled immediately after native settlement. */ +export interface CommandSignalAtSettlement { + readonly abortRequested: boolean; + readonly deadlineExpired: boolean; +} + /** Captured subprocess result. */ export interface CommandResult { readonly command: readonly string[]; @@ -18,6 +24,7 @@ export interface CommandResult { readonly stdout: string; readonly stderr: string; readonly timedOut: boolean; + readonly signalAtSettlement?: CommandSignalAtSettlement; } /** Port for running external commands. */ diff --git a/packages/cli/e2e/tests/adapters/commands/deno-command-adapter_test.ts b/packages/cli/e2e/tests/adapters/commands/deno-command-adapter_test.ts new file mode 100644 index 0000000000..2c61c56e49 --- /dev/null +++ b/packages/cli/e2e/tests/adapters/commands/deno-command-adapter_test.ts @@ -0,0 +1,61 @@ +import { assertEquals } from '@std/assert'; +import { DenoCommandAdapter } from '../../../src/adapters/commands/deno-command-adapter.ts'; + +for (const outputMode of ['capture', 'discard'] as const) { + Deno.test(`native ${outputMode} settlement retains the actual deadline state even if output resolves`, async () => { + let calls = 0; + const status = (options: Deno.CommandOptions): Promise => { + calls++; + return new Promise((resolve) => + options.signal!.addEventListener( + 'abort', + () => resolve({ code: 0, success: true, signal: null }), + { once: true }, + ) + ); + }; + const adapter = new DenoCommandAdapter({ + capture: async (_command, options) => ({ + ...await status(options), + stdout: new Uint8Array(), + stderr: new Uint8Array(), + }), + status: (_command, options) => status(options), + }); + const result = await adapter.run({ + command: ['inert-native'], + cwd: '.', + timeoutMs: 1, + outputMode, + }); + assertEquals(calls, 1); + assertEquals(result.code, 0); + assertEquals(result.signalAtSettlement, { abortRequested: true, deadlineExpired: true }); + assertEquals(result.timedOut, true, 'resolved output does not erase an observed deadline'); + }); +} +Deno.test('native nonzero and local exception do not imply a deadline or an observed child exit', async () => { + const native = { + capture: () => + Promise.resolve({ + code: 16, + success: false, + signal: null, + stdout: new Uint8Array(), + stderr: new Uint8Array(), + }), + status: () => Promise.resolve({ code: 16, success: false, signal: null }), + }; + const result = await new DenoCommandAdapter(native).run({ command: ['inert-native'], cwd: '.' }); + assertEquals(result.code, 16); + assertEquals(result.timedOut, false); + assertEquals(result.signalAtSettlement, { abortRequested: false, deadlineExpired: false }); + const failed = await new DenoCommandAdapter({ + ...native, + capture: () => Promise.reject(new Error('fixture-local-failure')), + }) + .run({ command: ['inert-native'], cwd: '.' }); + assertEquals(failed.code, 124); + assertEquals(failed.timedOut, false); + assertEquals(failed.signalAtSettlement, { abortRequested: false, deadlineExpired: false }); +});