@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/utils/codex-payload.js

@@ -0,0 +1,133 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse } from 'smol-toml';
+import { loadCodexManifest } from './codex-manifest.js';
+import { byteHash } from './snapshot-manifest.js';
+import { assertSafeFile, assertUniqueKeys, workspacePath } from './snapshot-paths.js';
+/** Resolve delivery resources from the installed adapter, never the consumer cwd. */
+export function resolvePackagedCodexDir(moduleDirectory) {
+    const candidates = [
+        join(moduleDirectory, 'resources/codex-plugin'),
+        join(moduleDirectory, '../resources/codex-plugin'),
+        join(moduleDirectory, '../../resources/codex-plugin'),
+        join(moduleDirectory, '../../../codex-plugin'),
+        join(moduleDirectory, '../../codex-plugin'),
+        join(moduleDirectory, '..'),
+    ];
+    return candidates
+        .map((path) => resolve(path))
+        .find((path) => existsSync(join(path, 'project-setup/manifest.json')));
+}
+function readResource(root, item) {
+    const path = workspacePath(root, item.source);
+    assertSafeFile(path);
+    const bytes = readFileSync(path);
+    if (byteHash(bytes) !== item.sha256)
+        throw new Error(`Codex payload hash mismatch: ${item.source}`);
+    return bytes;
+}
+/** Only generated guidance and the stable native runtime can be owned by setup. */
+export function validateCodexTarget(target) {
+    workspacePath('/codex-payload-validation', target);
+    if (!/^\.codex\/agents\/devsteps-[a-z0-9-]+\.toml$/.test(target) &&
+        !/^\.codex\/devsteps\/instructions\/.+/.test(target) &&
+        !/^\.agents\/skills\/(?:sdevsteps|devsteps)-[a-z0-9-]+\/.+/.test(target) &&
+        !/^\.agents\/skills\/devsteps\/(?:SKILL\.md|agents\/openai\.yaml)$/.test(target) &&
+        !/^\.codex\/devsteps\/runtime\/resources\/codex-plugin\/.+/.test(target) &&
+        !['.codex/devsteps/runtime/index.bundled.mjs', '.codex/devsteps/runtime/package.json'].includes(target)) {
+        throw new Error(`Unsupported Codex ownership target: ${target}`);
+    }
+}
+function validateGuidance(target, bytes) {
+    if (!target.endsWith('.toml'))
+        return;
+    const text = bytes.toString('utf8');
+    if (!Buffer.from(text).equals(bytes))
+        throw new Error(`Invalid UTF-8 in Codex role: ${target}`);
+    const document = parse(text);
+    if (Object.keys(document).some((key) => !['name', 'description', 'developer_instructions'].includes(key)) ||
+        !['name', 'description', 'developer_instructions'].every((key) => typeof document[key] === 'string'))
+        throw new Error(`Unsupported model or runtime policy in native Codex role: ${target}`);
+}
+function verifyIdentity(root, version, packageVersion) {
+    const path = workspacePath(root, 'plugin.json');
+    assertSafeFile(path);
+    const bytes = readFileSync(path);
+    const plugin = JSON.parse(bytes.toString('utf8'));
+    if (plugin.name !== 'devsteps' ||
+        plugin.version !== version ||
+        (packageVersion && version !== packageVersion)) {
+        throw new Error('Codex payload/plugin/package version provenance mismatch.');
+    }
+    return bytes;
+}
+function addNativeResources(files, resources, version) {
+    const metadata = files.get('.codex/devsteps/runtime/package.json');
+    if (!metadata)
+        throw new Error('Native Codex runtime metadata is missing.');
+    const pkg = JSON.parse(metadata.toString('utf8'));
+    if (pkg.name !== '@schnick371/devsteps-mcp-server' ||
+        pkg.version !== version ||
+        pkg.engines?.node !== '>=22') {
+        throw new Error('Codex runtime version or Node floor does not match its payload.');
+    }
+    for (const [key, bytes] of resources) {
+        files.set(`.codex/devsteps/runtime/resources/codex-plugin/${key}`, bytes);
+    }
+}
+/** Validate the entire declared payload before exposing any bytes to the planner. */
+export function readCodexPayload(root, mode, packageVersion) {
+    const { manifest, manifestBytes, overlayBytes } = loadCodexManifest(root);
+    const identity = verifyIdentity(root, manifest.version, packageVersion);
+    assertUniqueKeys(manifest.files.map((file) => file.target));
+    if (manifest.config &&
+        Object.keys(parse(readResource(root, manifest.config).toString('utf8'))).length) {
+        throw new Error('Codex payload config must not introduce project model or runtime policy.');
+    }
+    const files = new Map();
+    const resources = new Map([
+        ['project-setup/manifest.json', manifestBytes],
+        ['plugin.json', identity],
+    ]);
+    if (overlayBytes)
+        resources.set('server/runtime-manifest.json', overlayBytes);
+    resources.set(manifest.contract.source, readResource(root, manifest.contract));
+    if (manifest.config)
+        resources.set(manifest.config.source, readResource(root, manifest.config));
+    for (const file of manifest.files) {
+        validateCodexTarget(file.target);
+        const bytes = readResource(root, file);
+        if (file.target.startsWith('.codex/devsteps/runtime/resources/'))
+            throw new Error('Payload must not declare recursive setup resources.');
+        resources.set(file.source, bytes);
+        validateGuidance(file.target, bytes);
+        if (file.mode === 'both' || mode === 'native')
+            files.set(file.target, bytes);
+    }
+    if (manifest.runtime) {
+        if (manifest.runtime.target !== '.codex/devsteps/runtime/index.bundled.mjs')
+            throw new Error('Unsafe Codex runtime target.');
+        const bytes = readResource(root, manifest.runtime);
+        resources.set(manifest.runtime.source, bytes);
+        if (files.has(manifest.runtime.target))
+            throw new Error('Duplicate Codex runtime target.');
+        if (mode === 'native')
+            files.set(manifest.runtime.target, bytes);
+    }
+    else if (mode === 'native')
+        throw new Error('Native Codex setup requires an assembled runtime payload.');
+    if (mode === 'native')
+        addNativeResources(files, resources, manifest.version);
+    return {
+        version: manifest.version,
+        pluginId: manifest.pluginId,
+        contract: readResource(root, manifest.contract).toString('utf8'),
+        files,
+        runtimeTarget: manifest.runtime?.target,
+    };
+}
+//# sourceMappingURL=codex-payload.js.map

package/dist/utils/codex-payload.js.map

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

package/dist/utils/codex-plan.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+import { type CodexOptions, type CodexPlan } from './codex-types.js';
+/** Pure read/validate/plan: dry runs and no-op updates create no directories. */
+export declare function planCodexSetup(projectPath: string, options: CodexOptions): CodexPlan;
+//# sourceMappingURL=codex-plan.d.ts.map

package/dist/utils/codex-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-plan.d.ts","sourceRoot":"","sources":["../../src/utils/codex-plan.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAoI1B,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,SAAS,CA8BpF"}

package/dist/utils/codex-plan.js

@@ -0,0 +1,137 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+import { resolve } from 'node:path';
+import { parse } from 'smol-toml';
+import { planCodexConfig } from './codex-config.js';
+import { planCodexIgnore } from './codex-ignore.js';
+import { readCodexPayload } from './codex-payload.js';
+import { AGENTS_BEGIN, AGENTS_END, readCodexSpan, renderCodexSpan } from './codex-spans.js';
+import { readCodexLedger, readCodexTarget } from './codex-state.js';
+import { assertCodexOptions, CODEX_CONFIG, CODEX_LEDGER, } from './codex-types.js';
+import { byteHash } from './snapshot-manifest.js';
+import { validateWorkspaceTargets, workspacePath } from './snapshot-paths.js';
+function changed(before, after) {
+    return before === undefined ? after !== undefined : after === undefined || !before.equals(after);
+}
+function addChange(plan, path, file, before, after) {
+    if (changed(before, after)) {
+        plan.mutations.push({ path, before, after });
+        plan.statuses.push({
+            file,
+            status: after === undefined ? 'removed' : before === undefined ? 'added' : 'updated',
+        });
+    }
+    else
+        plan.statuses.push({ file, status: 'skipped', reason: 'hash-match' });
+}
+function planFiles(root, plan, ledger, next, payload, options) {
+    const expected = payload?.files ?? new Map();
+    const keys = [...new Set([...Object.keys(ledger?.files ?? {}), ...expected.keys()])].sort();
+    validateWorkspaceTargets(root, keys);
+    for (const key of keys) {
+        const path = workspacePath(root, key);
+        const before = readCodexTarget(path);
+        if (before && key.endsWith('.toml')) {
+            const text = before.toString('utf8');
+            if (!Buffer.from(text).equals(before))
+                throw new Error(`Invalid UTF-8 in Codex TOML: ${key}`);
+            parse(text);
+        }
+        const prior = ledger?.files[key];
+        const after = expected.get(key);
+        const edited = before !== undefined && (prior === undefined || byteHash(before) !== prior);
+        if (edited && prior === undefined && key.startsWith('.codex/devsteps/runtime/')) {
+            throw new Error(`Unowned native runtime conflicts with Codex setup: ${key}`);
+        }
+        if (edited && after === undefined && !options.remove && ledger?.mode !== plan.mode)
+            throw new Error(`Edited owned duplicate blocks Codex mode transition: ${key}`);
+        if (edited && (!options.force || prior === undefined || after === undefined)) {
+            plan.statuses.push({
+                file: key,
+                status: 'skipped',
+                reason: prior ? 'user-modified' : 'user-modified-no-ledger',
+            });
+            if (prior)
+                next.files[key] = prior;
+            continue;
+        }
+        if (after)
+            next.files[key] = byteHash(after);
+        addChange(plan, path, key, before, after);
+    }
+}
+function planAgents(root, plan, ledger, next, payload, options) {
+    const path = workspacePath(root, 'AGENTS.md');
+    const before = readCodexTarget(path);
+    if (options.remove && !ledger?.agents)
+        return;
+    const span = readCodexSpan(before, ledger?.agents, AGENTS_BEGIN, AGENTS_END);
+    if (span.edited && (!options.force || options.remove)) {
+        next.agents = ledger?.agents;
+        plan.statuses.push({ file: 'AGENTS.md', status: 'skipped', reason: 'user-modified' });
+        return;
+    }
+    const after = renderCodexSpan(span, payload?.contract, AGENTS_BEGIN, AGENTS_END);
+    next.agents = after.owned;
+    addChange(plan, path, 'AGENTS.md', before, after.bytes);
+}
+function planConfig(root, plan, ledger, next, payload, options) {
+    if (options.remove && !ledger?.config)
+        return;
+    const path = workspacePath(root, CODEX_CONFIG);
+    const before = readCodexTarget(path);
+    const after = planCodexConfig(root, before, ledger, plan.mode, payload, options);
+    next.config = after.owned;
+    addChange(plan, path, CODEX_CONFIG, before, after.bytes);
+}
+function finishLedger(root, plan, ledgerBytes, next, options) {
+    const retained = Object.keys(next.files).length || next.config || next.agents;
+    const ignore = planCodexIgnore(root, next.ignore, [
+        ...Object.keys(next.files),
+        ...(next.agents?.created ? ['AGENTS.md'] : []),
+        ...(next.config?.created ? [CODEX_CONFIG] : []),
+    ], !!options.remove && !retained);
+    next.ignore = ignore.owned;
+    if (ignore.path) {
+        addChange(plan, ignore.path, 'git:info/exclude', ignore.before, ignore.after);
+        const index = plan.mutations.findIndex((mutation) => mutation.path === ignore.path);
+        if (index >= 0)
+            plan.mutations.unshift(...plan.mutations.splice(index, 1));
+    }
+    const after = options.remove && !retained ? undefined : Buffer.from(`${JSON.stringify(next, null, 2)}\n`);
+    addChange(plan, workspacePath(root, CODEX_LEDGER), CODEX_LEDGER, ledgerBytes, after);
+}
+/** Pure read/validate/plan: dry runs and no-op updates create no directories. */
+export function planCodexSetup(projectPath, options) {
+    const root = resolve(projectPath);
+    assertCodexOptions('codex', options);
+    const { ledger, bytes } = readCodexLedger(root);
+    const mode = options.codexMode ?? ledger?.mode ?? 'native';
+    const plan = { mode, mutations: [], statuses: [], notes: [] };
+    if (options.remove && !ledger)
+        return plan;
+    if (!options.remove && !options.sourceCodexDir)
+        throw new Error('The installed package has no Codex payload resource.');
+    const payload = options.remove
+        ? undefined
+        : readCodexPayload(options.sourceCodexDir, mode, options.packageVersion);
+    const next = {
+        schemaVersion: 1,
+        host: 'codex',
+        mode,
+        version: payload?.version ?? ledger?.version ?? '',
+        files: {},
+        ignore: ledger?.ignore,
+    };
+    planFiles(root, plan, ledger, next, payload, options);
+    planAgents(root, plan, ledger, next, payload, options);
+    planConfig(root, plan, ledger, next, payload, options);
+    finishLedger(root, plan, bytes, next, options);
+    plan.notes.push(mode === 'plugin'
+        ? 'Project roles use the installed devsteps@devsteps plugin skills and MCP. Plugin installation is not verified.'
+        : 'Project skills and a stable project runtime are installed; the inherited DevSteps plugin is disabled for this project.');
+    return plan;
+}
+//# sourceMappingURL=codex-plan.js.map

package/dist/utils/codex-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-plan.js","sourceRoot":"","sources":["../../src/utils/codex-plan.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAqB,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,YAAY,GAIb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE9E,SAAS,OAAO,CAAC,MAA0B,EAAE,KAAyB;IACpE,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnG,CAAC;AAED,SAAS,SAAS,CAChB,IAAe,EACf,IAAY,EACZ,IAAY,EACZ,MAAe,EACf,KAAc;IAEd,IAAI,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACjB,IAAI;YACJ,MAAM,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;SACrF,CAAC,CAAC;IACL,CAAC;;QAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,SAAS,CAChB,IAAY,EACZ,IAAe,EACf,MAA+B,EAC/B,IAAiB,EACjB,OAAiC,EACjC,OAAqB;IAErB,MAAM,QAAQ,GAAG,OAAO,EAAE,KAAK,IAAI,IAAI,GAAG,EAAkB,CAAC;IAC7D,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5F,wBAAwB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACrC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAC;YAC9F,KAAK,CAAC,IAAI,CAAC,CAAC;QACd,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,KAAK,SAAS,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC,CAAC;QAC3F,IAAI,MAAM,IAAI,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,CAAC,0BAA0B,CAAC,EAAE,CAAC;YAChF,MAAM,IAAI,KAAK,CAAC,sDAAsD,GAAG,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,MAAM,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,MAAM,EAAE,IAAI,KAAK,IAAI,CAAC,IAAI;YAChF,MAAM,IAAI,KAAK,CAAC,wDAAwD,GAAG,EAAE,CAAC,CAAC;QACjF,IAAI,MAAM,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,CAAC,EAAE,CAAC;YAC7E,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBACjB,IAAI,EAAE,GAAG;gBACT,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,yBAAyB;aAC5D,CAAC,CAAC;YACH,IAAI,KAAK;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACnC,SAAS;QACX,CAAC;QACD,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7C,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CACjB,IAAY,EACZ,IAAe,EACf,MAA+B,EAC/B,IAAiB,EACjB,OAAiC,EACjC,OAAqB;IAErB,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,MAAM;QAAE,OAAO;IAC9C,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;IAC7E,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,IAAI,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;QACtF,OAAO;IACT,CAAC;IACD,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;IACjF,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,UAAU,CACjB,IAAY,EACZ,IAAe,EACf,MAA+B,EAC/B,IAAiB,EACjB,OAAiC,EACjC,OAAqB;IAErB,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,MAAM;QAAE,OAAO;IAC9C,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACjF,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,YAAY,CACnB,IAAY,EACZ,IAAe,EACf,WAA+B,EAC/B,IAAiB,EACjB,OAAqB;IAErB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAC9E,MAAM,MAAM,GAAG,eAAe,CAC5B,IAAI,EACJ,IAAI,CAAC,MAAM,EACX;QACE,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QAC1B,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,EACD,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,QAAQ,CAC9B,CAAC;IACF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9E,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC;QACpF,IAAI,KAAK,IAAI,CAAC;YAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,KAAK,GACT,OAAO,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9F,SAAS,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;AACvF,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,WAAmB,EAAE,OAAqB;IACvE,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,EAAE,IAAI,IAAI,QAAQ,CAAC;IAC3D,MAAM,IAAI,GAAc,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACzE,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,cAAc;QAC5C,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM;QAC5B,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,cAAwB,EAAE,IAAI,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACrF,MAAM,IAAI,GAAgB;QACxB,aAAa,EAAE,CAAC;QAChB,IAAI,EAAE,OAAO;QACb,IAAI;QACJ,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,OAAO,IAAI,EAAE;QAClD,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,MAAM,EAAE,MAAM;KACvB,CAAC;IACF,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACtD,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACvD,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACvD,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK,CAAC,IAAI,CACb,IAAI,KAAK,QAAQ;QACf,CAAC,CAAC,+GAA+G;QACjH,CAAC,CAAC,wHAAwH,CAC7H,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/codex-setup.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Shared Codex setup boundary: validate project identity before planning,
+ * snapshot preimages, then apply only revalidated mutations.
+ */
+import type { CodexOptions } from './codex-types.js';
+import type { UpdateAgentFilesResult } from './update-agent-files.js';
+/** Plan all surfaces, snapshot all preimages, then apply with honest partial-write reporting. */
+export declare function setupCodexProject(projectPath: string, devstepsDir: string, options?: CodexOptions, extraPreimages?: readonly string[]): UpdateAgentFilesResult;
+//# sourceMappingURL=codex-setup.d.ts.map

package/dist/utils/codex-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-setup.d.ts","sourceRoot":"","sources":["../../src/utils/codex-setup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EAAiB,YAAY,EAAa,MAAM,kBAAkB,CAAC;AAE/E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AA4DtE,iGAAiG;AACjG,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,YAAiB,EAC1B,cAAc,GAAE,SAAS,MAAM,EAAO,GACrC,sBAAsB,CAuDxB"}

package/dist/utils/codex-setup.js

@@ -0,0 +1,130 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Shared Codex setup boundary: validate project identity before planning,
+ * snapshot preimages, then apply only revalidated mutations.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { createWorkspaceSnapshot } from './agent-files-snapshot.js';
+import { renameWithRetrySync } from './atomic-write.js';
+import { planCodexSetup } from './codex-plan.js';
+import { readCodexTarget } from './codex-state.js';
+import { assertSafeDirectory, assertSafeFile } from './snapshot-paths.js';
+function result(plan, backupDir, dryRun) {
+    const count = (status) => plan.statuses.filter((file) => file.status === status).length;
+    return {
+        success: true,
+        addedCount: count('added'),
+        updatedCount: count('updated'),
+        removedCount: count('removed'),
+        skippedCount: count('skipped'),
+        backupDir,
+        files: plan.statuses,
+        message: `${dryRun ? '[dry-run] ' : ''}Codex ${plan.mode}: ${plan.mutations.length} planned file changes. ${plan.notes.join(' ')}`,
+    };
+}
+/** Revalidate every preimage together, both before and after the completed snapshot. */
+function validatePreimages(mutations) {
+    for (const mutation of mutations) {
+        const current = readCodexTarget(mutation.path);
+        if (mutation.before === undefined ? current !== undefined : !current?.equals(mutation.before)) {
+            throw new Error(`Codex target changed during setup: ${mutation.path}`);
+        }
+    }
+}
+/** Per-file atomic writes avoid truncation; completed preimages remain available after failures. */
+function applyMutation(mutation) {
+    validatePreimages([mutation]);
+    assertSafeFile(mutation.path, true);
+    if (mutation.after === undefined) {
+        unlinkSync(mutation.path);
+        return;
+    }
+    mkdirSync(dirname(mutation.path), { recursive: true });
+    assertSafeDirectory(dirname(mutation.path));
+    const temporary = `${mutation.path}.devsteps-${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, mutation.after, { flag: 'wx', mode: 0o600 });
+        assertSafeFile(mutation.path, true);
+        renameWithRetrySync(temporary, mutation.path, () => validatePreimages([mutation]));
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* Preserve the original write diagnostic. */
+        }
+        throw error;
+    }
+}
+/** Include Git's resolved exclude preimage even when linked Git stores it outside the project. */
+function snapshotRoot(project, mutations) {
+    let root = resolve(project);
+    for (const mutation of mutations) {
+        while (relative(root, mutation.path).split(/[\\/]/)[0] === '..')
+            root = dirname(root);
+    }
+    return root;
+}
+/** Plan all surfaces, snapshot all preimages, then apply with honest partial-write reporting. */
+export function setupCodexProject(projectPath, devstepsDir, options = {}, extraPreimages = []) {
+    let backupDir = '';
+    let plan;
+    let applied = 0;
+    let snapshotComplete = false;
+    try {
+        // Reject links before realpath hides them; all adapters then plan from the
+        // same filesystem spelling, including Windows drive casing and separators.
+        assertSafeDirectory(projectPath);
+        const rootPath = realpathSync.native(projectPath);
+        plan = planCodexSetup(rootPath, options);
+        if (options.dryRun || (!plan.mutations.length && !extraPreimages.length))
+            return result(plan, '', !!options.dryRun);
+        const extras = extraPreimages.map((path) => ({ path, before: readCodexTarget(path) }));
+        validatePreimages(plan.mutations);
+        const preimages = [...plan.mutations, ...extras];
+        const root = snapshotRoot(rootPath, preimages);
+        const keys = [
+            ...new Set(preimages
+                .filter((entry) => entry.before !== undefined)
+                .map((entry) => relative(root, entry.path).split('\\').join('/'))),
+        ];
+        const backup = createWorkspaceSnapshot(root, devstepsDir, keys, {
+            maxBackups: options.maxBackups,
+            packageVersion: options.packageVersion,
+        });
+        backupDir = backup.backupDir;
+        if (!backup.success)
+            throw new Error(`Backup failed; setup aborted: ${backup.error?.message}`);
+        snapshotComplete = true;
+        validatePreimages(plan.mutations);
+        validatePreimages(extras);
+        for (const mutation of plan.mutations) {
+            applyMutation(mutation);
+            applied++;
+        }
+        return result(plan, backupDir, false);
+    }
+    catch (error) {
+        return {
+            success: false,
+            addedCount: 0,
+            updatedCount: 0,
+            removedCount: 0,
+            skippedCount: 0,
+            backupDir,
+            files: plan?.statuses ?? [],
+            message: applied
+                ? `Codex setup failed after ${applied} file writes; snapshot preserved at ${backupDir}.`
+                : snapshotComplete && backupDir
+                    ? `Codex setup failed before target changes; snapshot preserved at ${backupDir}.`
+                    : 'Codex setup refused before target changes.',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+//# sourceMappingURL=codex-setup.js.map

package/dist/utils/codex-setup.js.map

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

package/dist/utils/codex-spans.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+import type { CodexSpan } from './codex-types.js';
+export declare const CONFIG_BEGIN = "# devsteps-codex:begin";
+export declare const CONFIG_END = "# devsteps-codex:end";
+export declare const AGENTS_BEGIN = "<!-- devsteps-codex:begin -->";
+export declare const AGENTS_END = "<!-- devsteps-codex:end -->";
+export declare const IGNORE_BEGIN = "# devsteps-codex-ignore:begin";
+export declare const IGNORE_END = "# devsteps-codex-ignore:end";
+export interface SpanRead {
+    existed: boolean;
+    before: string;
+    remainder: string;
+    start?: number;
+    end?: number;
+    edited: boolean;
+    owned?: CodexSpan;
+}
+/** Exact markers and ledger hashes bound edits without reserializing project bytes. */
+export declare function readCodexSpan(bytes: Buffer | undefined, owned: CodexSpan | undefined, begin: string, end: string): SpanRead;
+export declare function renderCodexSpan(current: SpanRead, body: string | undefined, begin: string, end: string): {
+    bytes?: Buffer;
+    owned?: CodexSpan;
+};
+//# sourceMappingURL=codex-spans.d.ts.map

package/dist/utils/codex-spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-spans.d.ts","sourceRoot":"","sources":["../../src/utils/codex-spans.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,eAAO,MAAM,YAAY,2BAA2B,CAAC;AACrD,eAAO,MAAM,UAAU,yBAAyB,CAAC;AACjD,eAAO,MAAM,YAAY,kCAAkC,CAAC;AAC5D,eAAO,MAAM,UAAU,gCAAgC,CAAC;AACxD,eAAO,MAAM,YAAY,kCAAkC,CAAC;AAC5D,eAAO,MAAM,UAAU,gCAAgC,CAAC;AAExD,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,uFAAuF;AACvF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,QAAQ,CAkCV;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAuBvC"}

package/dist/utils/codex-spans.js

@@ -0,0 +1,69 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+import { byteHash } from './snapshot-manifest.js';
+export const CONFIG_BEGIN = '# devsteps-codex:begin';
+export const CONFIG_END = '# devsteps-codex:end';
+export const AGENTS_BEGIN = '<!-- devsteps-codex:begin -->';
+export const AGENTS_END = '<!-- devsteps-codex:end -->';
+export const IGNORE_BEGIN = '# devsteps-codex-ignore:begin';
+export const IGNORE_END = '# devsteps-codex-ignore:end';
+/** Exact markers and ledger hashes bound edits without reserializing project bytes. */
+export function readCodexSpan(bytes, owned, begin, end) {
+    const before = bytes?.toString('utf8') ?? '';
+    if (bytes && !Buffer.from(before).equals(bytes))
+        throw new Error('Managed text is not valid UTF-8.');
+    const starts = before.split(begin).length - 1;
+    const ends = before.split(end).length - 1;
+    if (!starts && !ends) {
+        if (owned)
+            throw new Error(`Managed span disappeared: ${begin}`);
+        return { before, remainder: before, edited: false, existed: bytes !== undefined };
+    }
+    if (starts !== 1 || ends !== 1 || !owned)
+        throw new Error(`Ambiguous or unowned managed span: ${begin}`);
+    const markerStart = before.indexOf(begin);
+    const markerEnd = before.indexOf(end);
+    const start = markerStart - owned.prefix.length;
+    const finish = markerEnd + end.length + 1;
+    if (markerEnd < markerStart ||
+        start < 0 ||
+        before.slice(start, markerStart) !== owned.prefix ||
+        (markerStart > 0 && before[markerStart - 1] !== '\n') ||
+        before[finish - 1] !== '\n')
+        throw new Error(`Malformed managed span: ${begin}`);
+    const text = before.slice(markerStart, finish);
+    return {
+        existed: bytes !== undefined,
+        before,
+        remainder: before.slice(0, start) + before.slice(finish),
+        start,
+        end: finish,
+        edited: byteHash(Buffer.from(text)) !== owned.sha256,
+        owned,
+    };
+}
+export function renderCodexSpan(current, body, begin, end) {
+    if (body === undefined) {
+        const remainder = current.remainder;
+        return {
+            bytes: current.owned?.created && remainder === '' ? undefined : Buffer.from(remainder),
+        };
+    }
+    const text = `${begin}\n${body.trimEnd()}\n${end}\n`;
+    const prefix = current.owned?.prefix ??
+        (current.before === '' ? '' : current.before.endsWith('\n') ? '\n' : '\n\n');
+    const content = current.start === undefined
+        ? `${current.before}${prefix}${text}`
+        : current.before.slice(0, current.start) + prefix + text + current.before.slice(current.end);
+    return {
+        bytes: Buffer.from(content),
+        owned: {
+            sha256: byteHash(Buffer.from(text)),
+            prefix,
+            created: current.owned?.created ?? !current.existed,
+        },
+    };
+}
+//# sourceMappingURL=codex-spans.js.map

package/dist/utils/codex-spans.js.map

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

package/dist/utils/codex-state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+import { type CodexLedger } from './codex-types.js';
+/** A malformed or unsafe ledger is never interpreted as an absent installation. */
+export declare function readCodexLedger(root: string): {
+    ledger?: CodexLedger;
+    bytes?: Buffer;
+};
+export declare function readCodexTarget(path: string): Buffer | undefined;
+/** Host setup can create snapshots before the project itself has been initialized. */
+export declare function hasOnlyCodexSnapshots(devstepsDir: string): boolean;
+//# sourceMappingURL=codex-state.d.ts.map

package/dist/utils/codex-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-state.d.ts","sourceRoot":"","sources":["../../src/utils/codex-state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA0BlE,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAStF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhE;AAED,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAqBlE"}