cursedbelt 2.7.0 → 3.0.0

package/src/verify/manifestFidelity.spec.ts

@@ -1,67 +0,0 @@
-/**
- * The pipeline-fidelity static gate (06 §4, Law #4).
- *
- * The op-allowlist bug shipped because a suite HAND-BUILT the `EffectiveManifest` /
- * `EffectiveInstance` the pipeline should derive, so it proved the mixin, not the
- * product. This gate keeps that class from recurring: any `*.spec` that constructs a
- * manifest/instance value must either (a) DERIVE it through `verifyAppConfig` — the
- * real V2 the generated app runs — or (b) carry a one-line `manifest-fidelity-allow:`
- * annotation declaring WHY it is a legitimate boundary unit (a router/CSP/client-render
- * test whose subject is not the derivation). A new bypasser that does neither fails
- * HERE, in review, instead of silently shipping a weaker guarantee than it reads.
- *
- * This is stronger than the "warning-level" the spec floated: a warning nobody gates on
- * is exactly the kind of inert check file 06 exists to replace with teeth. The opt-out
- * keeps the legitimate boundary units green while making every one of them a documented,
- * greppable decision rather than an invisible gap.
- *
- * The heuristic is deliberately lightweight (06 §4's own framing: "without a nearby
- * verifyAppConfig call"): a file "constructs a manifest" iff it names `EffectiveManifest`
- * or `EffectiveInstance`. That over-includes a file that merely imports the type for a
- * signature — which is fine: such a file adds one annotation line, and the visible list
- * of allow-annotations stays a useful census of every non-derived manifest touch.
- */
-import { describe, expect, it } from 'bun:test';
-import { readFileSync, readdirSync } from 'node:fs';
-import { extname, join, relative } from 'node:path';
-
-const SRC_ROOT = join(import.meta.dir, '..');
-const MANIFEST_TYPES = /\bEffective(?:Manifest|Instance)\b/;
-const DERIVES = /\bverifyAppConfig\b/;
-const ALLOW = /manifest-fidelity-allow:/;
-/** This checker names the types in its own prose; it is not a manifest bypasser. */
-const SELF = 'manifestFidelity.spec.ts';
-
-const specFiles = (dir: string, out: string[] = []): string[] => {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name.startsWith('___')) continue;
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) specFiles(full, out);
-    else if (/\.spec\.tsx?$/.test(entry.name) && ['.ts', '.tsx'].includes(extname(entry.name))) out.push(full);
-  }
-  return out;
-};
-
-describe('manifest fidelity — hand-built manifests must derive or declare (06 §4)', () => {
-  const files = specFiles(SRC_ROOT).filter((f) => !f.endsWith(SELF));
-
-  const bypassers = files.filter((file) => {
-    const source = readFileSync(file, 'utf8');
-    return MANIFEST_TYPES.test(source) && !DERIVES.test(source);
-  });
-
-  it('every non-deriving manifest spec carries a manifest-fidelity-allow annotation', () => {
-    const undocumented = bypassers
-      .filter((file) => !ALLOW.test(readFileSync(file, 'utf8')))
-      .map((file) => relative(SRC_ROOT, file));
-    // Each entry: convert it to derive via verifyAppConfig, or (if it is a legitimate
-    // boundary unit) add a `manifest-fidelity-allow: <reason>` line to its docblock.
-    expect(undocumented).toEqual([]);
-  });
-
-  it('at least one bypasser is a declared boundary unit (the gate is actually wired)', () => {
-    // A sanity check that the scan resolves real files — a zero-file scan (e.g. a moved
-    // SRC_ROOT) would make the gate above vacuously pass.
-    expect(files.length).toBeGreaterThan(20);
-  });
-});

package/src/verify/pipeline.spec.ts

@@ -1,142 +0,0 @@
-/**
- * The four run moments share ONE implementation (04 §1). These specs pin the two
- * things that are allowed to differ — where capabilities come from, and what the
- * caller does with a failure — and assert that nothing else does.
- */
-import { describe, expect, it } from 'bun:test';
-import { fixtureConfig } from './fixtures/index';
-import { formatDiagnostics, resolveBootConfig, toArtifacts, verifyAppConfig } from './pipeline';
-import type { SourceDecl, VerifyMoment } from './types';
-
-const VAULT: SourceDecl = { id: 'vault-media', token: 'media:videos', exportable: true, itemCount: 3 };
-const FULL = { ffmpeg: true, wasm: true, shell: true, aiProvider: true, diskIndex: true, network: true, ocrRuntime: true, git: true };
-
-const run = (name: string, moment: VerifyMoment, extra: Record<string, unknown> = {}) =>
-  verifyAppConfig({ config: fixtureConfig(name), moment, capabilities: FULL, sources: [VAULT], ...extra });
-
-describe('one pipeline, four moments', () => {
-  it('produces the identical diagnostic set at studio, boot and CI for the same inputs', async () => {
-    const moments: VerifyMoment[] = ['studio', 'boot', 'ci'];
-    const results = await Promise.all(moments.map((moment) => run('av-video-off-wired', moment)));
-    const codes = results.map((r) => r.diagnostics.map((d) => `${d.severity}:${d.code}`).sort());
-    expect(codes[1]).toEqual(codes[0] as string[]);
-    expect(codes[2]).toEqual(codes[0] as string[]);
-  });
-
-  it('reads live-probe capabilities at studio/boot and the declared deploy target at export (J4-B)', async () => {
-    const noFfmpeg = { ...FULL, ffmpeg: false };
-    const atBoot = await run('av-export-target-branch', 'boot', { capabilities: noFfmpeg });
-    const atExport = await run('av-export-target-branch', 'export', { capabilities: noFfmpeg });
-
-    expect(atBoot.manifest?.capabilitySource).toBe('live-probe');
-    expect(atBoot.diagnostics.map((d) => d.code)).toContain('capability-downgrade');
-
-    expect(atExport.manifest?.capabilitySource).toBe('deploy-target');
-    expect(atExport.diagnostics).toEqual([]);
-  });
-
-  it('marks CI capabilities as a pinned fixture profile', async () => {
-    const result = await run('av-baseline', 'ci');
-    expect(result.manifest?.capabilitySource).toBe('pinned-fixture');
-  });
-});
-
-describe('stage sequencing', () => {
-  it('stops at V0 when the config does not parse — there is nothing to resolve', async () => {
-    const result = await run('unknown-key', 'ci');
-    expect(result.lastStage).toBe('V0');
-    expect(result.manifest).toBeNull();
-  });
-
-  it('stops at V1 when a reference does not resolve', async () => {
-    const result = await run('route-collision', 'ci');
-    expect(result.lastStage).toBe('V1');
-    expect(result.manifest).toBeNull();
-  });
-
-  it('keeps running V2–V6 after a V2 error so one pass reports every defect', async () => {
-    const result = await run('av-cycle-editor-off', 'ci');
-    expect(result.lastStage).toBe('V6');
-    const codes = new Set(result.diagnostics.map((d) => d.code));
-    expect(codes.has('port-disabled-by-config')).toBe(true); // V2
-    expect(codes.has('cycle-broken-by-config')).toBe(true); // V4
-  });
-});
-
-describe('the effective manifest', () => {
-  it('materializes per-instance effective features, ports and ops', async () => {
-    const result = await run('av-two-instances-divergent', 'ci');
-    const gallery = result.manifest?.instances.find((i) => i.id === 'gallery');
-    const editor = result.manifest?.instances.find((i) => i.id === 'editor');
-
-    expect(gallery?.effective.hls).toBe(true);
-    expect(editor?.effective.hls).toBe(false);
-    expect(gallery?.effectiveFeaturesHash).not.toBe(editor?.effectiveFeaturesHash);
-
-    // hls off ⇒ the transcode op leaves the allowlist; the video ports stay (degrade, not fail-closed).
-    expect(gallery?.ops.map((o) => o.id)).toContain('transcode');
-    expect(editor?.ops.map((o) => o.id)).not.toContain('transcode');
-    expect(editor?.ports.find((p) => p.spec.id === 'videos-out')?.enabled).toBe(true);
-  });
-
-  it('removes ports whose enabledWhen is false — the fail-closed law (04 §3)', async () => {
-    const result = await run('av-video-off-wired', 'ci');
-    const gallery = result.manifest?.instances.find((i) => i.id === 'gallery');
-    expect(gallery?.ports.find((p) => p.spec.id === 'videos-in')?.enabled).toBe(false);
-    expect(gallery?.ports.find((p) => p.spec.id === 'photos-out')?.enabled).toBe(true);
-  });
-
-  it('gives configs with different effective features different bundle keys (V5)', async () => {
-    const baseline = await run('av-baseline', 'ci');
-    const hlsOff = await run('av-hls-off-inbound-videos', 'ci');
-    expect(baseline.manifest?.bundleKey).not.toBe(hlsOff.manifest?.bundleKey);
-    expect(baseline.manifest?.requiredTiers).toContain('hls.js');
-    expect(hlsOff.manifest?.requiredTiers).not.toContain('hls.js');
-  });
-
-  it('is byte-stable across repeated compilations of the same input', async () => {
-    const first = await run('av-baseline', 'ci');
-    const second = await run('av-baseline', 'ci');
-    expect(second.manifest?.bundleKey).toBe(first.manifest?.bundleKey as string);
-    expect(JSON.stringify(toArtifacts(second).diagnostics)).toBe(JSON.stringify(toArtifacts(first).diagnostics));
-  });
-});
-
-describe('boot disposition — last-good bundle (04 §1, V7.6)', () => {
-  it('serves the new manifest when the config verifies', async () => {
-    const good = await resolveBootConfig({ config: fixtureConfig('av-baseline'), moment: 'boot', capabilities: FULL, sources: [VAULT] });
-    expect(good.servedLastGood).toBe(false);
-    expect(good.manifest?.appId).toBe('av-baseline');
-  });
-
-  it('keeps serving the previous bundle when a bad config arrives', async () => {
-    const good = await resolveBootConfig({ config: fixtureConfig('av-baseline'), moment: 'boot', capabilities: FULL, sources: [VAULT] });
-    const bad = await resolveBootConfig(
-      { config: fixtureConfig('av-video-off-wired'), moment: 'boot', capabilities: FULL, sources: [VAULT] },
-      good.manifest,
-    );
-    expect(bad.result.ok).toBe(false);
-    expect(bad.servedLastGood).toBe(true);
-    expect(bad.manifest?.appId).toBe('av-baseline');
-  });
-
-  it('has no bundle to fall back to on a first boot, and says so rather than pretending', async () => {
-    const bad = await resolveBootConfig({ config: fixtureConfig('av-video-off-wired'), moment: 'boot', capabilities: FULL, sources: [VAULT] });
-    expect(bad.manifest).toBeNull();
-    expect(bad.servedLastGood).toBe(false);
-  });
-});
-
-describe('diagnostic rendering', () => {
-  it('prints code, location, message and fix for every diagnostic', async () => {
-    const result = await run('av-video-off-wired', 'ci');
-    const rendered = formatDiagnostics(result);
-    expect(rendered).toContain('port-disabled-by-config');
-    expect(rendered).toContain('gallery');
-    expect(rendered).toContain('fix:');
-  });
-
-  it('says so plainly when there is nothing to report', async () => {
-    expect(formatDiagnostics(await run('av-baseline', 'ci'))).toBe('No diagnostics.');
-  });
-});

package/src/verify/pipeline.ts

@@ -1,149 +0,0 @@
-/**
- * The verification pipeline — ONE implementation, four run moments (04 §1).
- *
- * Studio, export, boot and CI all call `verifyAppConfig`. They differ in exactly
- * two things: where capabilities come from (J4-B) and what the caller does with
- * the result (inline diagnostics vs a hard gate). There is deliberately no
- * "studio mode" branch inside a stage — rule skew between design time and boot
- * time is the failure this pipeline exists to make impossible.
- *
- * Stage sequencing: V0 and V1 are gates. If the config does not parse, there is
- * nothing to resolve; if references do not resolve, ports and wires are
- * meaningless and every later stage would emit noise about a config the author
- * already has to fix. From V2 on, stages keep running even when an earlier one
- * errored, because the extra diagnostics are about different defects and fixing
- * them in one pass beats four rounds of re-running the build.
- */
-import { createTokenRegistry } from '../core/tokens/registry';
-import type { PipelineState } from './context';
-import { DiagnosticBag, sortDiagnostics } from './diagnostics';
-import { ENGINE_CATALOG, engineCatalogIndex } from './engines';
-import { runV0 } from './stages/v0Parse';
-import { runV1 } from './stages/v1References';
-import { runV2 } from './stages/v2Capabilities';
-import { runV3 } from './stages/v3Tokens';
-import { runV4 } from './stages/v4Graph';
-import { runV5 } from './stages/v5Export';
-import { runV6 } from './stages/v6Storage';
-import type { EffectiveManifest, VerifyInput, VerifyResult } from './types';
-
-export function createPipelineState(input: VerifyInput): PipelineState {
-  const registry = createTokenRegistry();
-  for (const marshaller of input.marshallers ?? []) registry.registerMarshaller(marshaller);
-  return {
-    input,
-    moment: input.moment,
-    config: null,
-    engines: engineCatalogIndex(input.engines ?? ENGINE_CATALOG),
-    registry,
-    catalogs: [],
-    harvestRetriedPaths: [],
-    sources: new Map((input.sources ?? []).map((source) => [source.id, source])),
-    wires: [],
-    declaredPorts: new Map(),
-    instances: [],
-    instanceIndex: new Map(),
-    capabilities: input.capabilities ?? {},
-    capabilitySource: input.moment === 'export' ? 'deploy-target' : input.moment === 'ci' ? 'pinned-fixture' : 'live-probe',
-    requiredTiers: [],
-    cspConnectAllowlist: [],
-    bundleKey: '',
-  };
-}
-
-function buildManifest(state: PipelineState): EffectiveManifest | null {
-  const config = state.config;
-  if (!config) return null;
-  return {
-    appId: config.app.id,
-    title: config.app.title,
-    profile: config.profile,
-    moment: state.moment,
-    engines: config.engines,
-    instances: state.instances,
-    connections: config.connections.map((c) => ({ from: c.from, to: c.to, cyclic: c.cyclic })),
-    cspConnectAllowlist: state.cspConnectAllowlist,
-    bundleKey: state.bundleKey,
-    requiredTiers: state.requiredTiers,
-    capabilities: state.capabilities,
-    capabilitySource: state.capabilitySource,
-    tokenIds: state.registry.ids(),
-    stagingCatalogs: state.catalogs,
-    // Carried, not recomputed: the schema has already validated every custom
-    // property name and value (E7), so V2's job is to stop dropping it.
-    theme: config.theme,
-  };
-}
-
-/**
- * Compile a config into an EffectiveManifest + diagnostics. Never throws for
- * config-level problems — a compiler that crashes cannot report what was wrong.
- */
-export async function verifyAppConfig(input: VerifyInput): Promise<VerifyResult> {
-  const state = createPipelineState(input);
-  const bag = new DiagnosticBag();
-
-  await runV0(state, bag);
-  if (bag.hasErrors() || state.config === null)
-    return { manifest: null, diagnostics: bag.all(), ok: false, lastStage: 'V0' };
-
-  const beforeV1 = bag.mark();
-  runV1(state, bag);
-  if (bag.countFrom(beforeV1) > 0)
-    return { manifest: null, diagnostics: bag.all(), ok: false, lastStage: 'V1' };
-
-  runV2(state, bag);
-  runV3(state, bag);
-  runV4(state, bag);
-  runV5(state, bag);
-  runV6(state, bag);
-
-  return {
-    manifest: buildManifest(state),
-    diagnostics: bag.all(),
-    ok: !bag.hasErrors(),
-    lastStage: 'V6',
-  };
-}
-
-/**
- * Boot disposition (04 §1): the server keeps serving its last-good bundle rather
- * than dying on a bad config edit. Returns the manifest to serve.
- */
-export async function resolveBootConfig(
-  input: VerifyInput,
-  lastGood: EffectiveManifest | null = null,
-): Promise<{ manifest: EffectiveManifest | null; result: VerifyResult; servedLastGood: boolean }> {
-  const result = await verifyAppConfig({ ...input, moment: 'boot' });
-  if (result.ok && result.manifest) return { manifest: result.manifest, result, servedLastGood: false };
-  return { manifest: lastGood, result, servedLastGood: lastGood !== null };
-}
-
-export interface VerifyArtifacts {
-  manifest: EffectiveManifest | null;
-  diagnostics: ReturnType<typeof sortDiagnostics>;
-  ok: boolean;
-  lastStage: VerifyResult['lastStage'];
-}
-
-/** The `___gen/verify/` payload — stable ordering so a diff means a real change. */
-export function toArtifacts(result: VerifyResult): VerifyArtifacts {
-  return {
-    manifest: result.manifest,
-    diagnostics: sortDiagnostics(result.diagnostics),
-    ok: result.ok,
-    lastStage: result.lastStage,
-  };
-}
-
-/** Human-readable one-line-per-diagnostic rendering for CLI output. */
-export function formatDiagnostics(result: VerifyResult): string {
-  if (result.diagnostics.length === 0) return 'No diagnostics.';
-  return sortDiagnostics(result.diagnostics)
-    .map((d) => {
-      const location = [d.instanceId, d.port, d.path].filter(Boolean).join(' ');
-      const fix = d.fix ? `\n      fix: ${d.fix}` : '';
-      return `  ${d.severity.toUpperCase().padEnd(7)} ${d.code}${location ? ` [${location}]` : ''}\n      ${d.message}${fix}`;
-    })
-    .join('\n');
-}

package/src/verify/pluginLoader.spec.ts

@@ -1,78 +0,0 @@
-/**
- * "Zero plugin-loader code in generated output" (02 §1.4) — the scanner and the
- * V5 rule that share it.
- */
-import { describe, expect, it } from 'bun:test';
-import { detectPluginLoaderCode, findPluginLoaderViolations } from './pluginLoader';
-import { verifyAppConfig } from './pipeline';
-
-describe('detectPluginLoaderCode', () => {
-  it('catches every legacy runtime-registration shape', () => {
-    expect(detectPluginLoaderCode('const rt = createPluginRuntime();')).toEqual(['createPluginRuntime()']);
-    expect(detectPluginLoaderCode('registerFromCatalog(rt, ids)')).toEqual(['registerFromCatalog()']);
-    expect(detectPluginLoaderCode('app.route("/", buildServerRouter(rt, cfg, { verifyToken }))')).toEqual([
-      'buildServerRouter()',
-    ]);
-    expect(detectPluginLoaderCode('runtime.plugins.register(todoPlugin)')).toEqual(['runtime.plugins.register()']);
-    expect(detectPluginLoaderCode('for (const f of PLUGIN_FACTORIES) f()')).toEqual(['PLUGIN_FACTORIES']);
-  });
-
-  it('does not accuse prose ABOUT the ban', () => {
-    const doc = `/**
- * The generated server never calls createPluginRuntime() — discovery is
- * compile-time (02 §1.4).
- */
-// registerFromCatalog() belongs to the legacy target only.
-import { bootEngineApp } from 'cursedbelt/server/runtime';`;
-    expect(detectPluginLoaderCode(doc)).toEqual([]);
-  });
-
-  it('passes a real engine-model server body', () => {
-    const server = `import { bootEngineApp, serveCcApp } from 'cursedbelt/server/runtime';
-const runtime = bootEngineApp({ manifest: MANIFEST, root, telemetry, allowedOrigins });
-serveCcApp({ runtime, port });`;
-    expect(detectPluginLoaderCode(server)).toEqual([]);
-  });
-
-  it('reports per file', () => {
-    expect(
-      findPluginLoaderViolations([
-        { path: 'server.ts', source: 'bootEngineApp({})' },
-        { path: 'client/main.tsx', source: 'createPluginRuntime()' },
-      ]),
-    ).toEqual([{ path: 'client/main.tsx', calls: ['createPluginRuntime()'] }]);
-  });
-});
-
-describe('V5 generated-app-plugin-loader', () => {
-  const CONFIG = {
-    configVersion: 1,
-    app: { id: 'closed-bundle', title: 'Closed Bundle' },
-    profile: 'local',
-    engines: ['system'],
-    instances: [{ engine: 'system', id: 'utils', features: {} }],
-  };
-
-  it('errors when emitted output re-opens the loader world', async () => {
-    const result = await verifyAppConfig({
-      config: CONFIG,
-      moment: 'export',
-      capabilities: {},
-      code: { generatedSources: [{ path: 'server.ts', source: 'const rt = createPluginRuntime();' }] },
-    });
-    const diagnostic = result.diagnostics.find((d) => d.code === 'generated-app-plugin-loader');
-    expect(diagnostic?.severity).toBe('error');
-    expect(diagnostic?.message).toContain('server.ts');
-    expect(result.ok).toBe(false);
-  });
-
-  it('stays silent for loader-free output', async () => {
-    const result = await verifyAppConfig({
-      config: CONFIG,
-      moment: 'export',
-      capabilities: {},
-      code: { generatedSources: [{ path: 'server.ts', source: "import { bootEngineApp } from 'cursedbelt/server/runtime';" }] },
-    });
-    expect(result.diagnostics.some((d) => d.code === 'generated-app-plugin-loader')).toBe(false);
-  });
-});

package/src/verify/pluginLoader.ts

@@ -1,67 +0,0 @@
-/**
- * "Zero plugin-loader code in generated output" (02 §1.4), as a check rather than
- * a promise.
- *
- * The engine model's central claim is that discovery is **compile-time**: the
- * generated server is a flat list of static imports and the bundle is closed. A
- * single `runtime.plugins.register(...)` in emitted output re-opens the old
- * world — code that exists only because something registered it at boot, invisible
- * to the manifest, to V5's bundle accounting, and to every gate that reasons about
- * "what does this app contain".
- *
- * ONE implementation, two callers, deliberately:
- *   * the generator scans its own emitted files before writing them (a failure
- *     there aborts generation — the output never reaches disk);
- *   * V5 emits `generated-app-plugin-loader` for sources handed to the pipeline,
- *     so the corpus and the studio see the same verdict.
- *
- * The scan is textual and conservative: it looks for the loader call SHAPES the
- * legacy framework actually exposes, and it ignores comments so a doc comment
- * naming `createPluginRuntime` (like this one) is not itself a violation.
- */
-
-/** The legacy runtime-registration call shapes that must not appear in output. */
-const LOADER_PATTERNS: readonly { readonly re: RegExp; readonly what: string }[] = [
-  { re: /\bcreatePluginRuntime\s*\(/, what: 'createPluginRuntime()' },
-  { re: /\bregisterFromCatalog\s*\(/, what: 'registerFromCatalog()' },
-  { re: /\bbuildServerRouter\s*\(/, what: 'buildServerRouter()' },
-  { re: /\bvalidateAndLoadConfig\s*\(/, what: 'validateAndLoadConfig()' },
-  { re: /\bresolveShellConfig\s*\(/, what: 'resolveShellConfig()' },
-  { re: /\.plugins\s*\.\s*register\s*\(/, what: 'runtime.plugins.register()' },
-  { re: /\bPLUGIN_FACTORIES\b/, what: 'PLUGIN_FACTORIES' },
-];
-
-/**
- * Strip line and block comments so prose about the ban is not a violation of it.
- * Deliberately not a parser: string literals containing `//` are over-stripped,
- * which can only ever cause a MISSED detection in emitted code we also control —
- * never a false accusation against a legitimate file.
- */
-const stripComments = (source: string): string => source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/[^\n]*/g, '$1');
-
-/** Every runtime plugin-registration call shape found in `source`. */
-export function detectPluginLoaderCode(source: string): string[] {
-  const code = stripComments(source);
-  return LOADER_PATTERNS.filter((pattern) => pattern.re.test(code)).map((pattern) => pattern.what);
-}
-
-export interface GeneratedSource {
-  /** Path (or basename) reported in the diagnostic. */
-  path: string;
-  source: string;
-}
-
-export interface PluginLoaderViolation {
-  path: string;
-  calls: readonly string[];
-}
-
-/** Scan a whole emitted file set. Empty ⇒ the output is loader-free. */
-export function findPluginLoaderViolations(files: readonly GeneratedSource[]): PluginLoaderViolation[] {
-  const violations: PluginLoaderViolation[] = [];
-  for (const file of files) {
-    const calls = detectPluginLoaderCode(file.source);
-    if (calls.length > 0) violations.push({ path: file.path, calls });
-  }
-  return violations;
-}

package/src/verify/promotion/bin/ccPromote.ts

@@ -1,147 +0,0 @@
-#!/usr/bin/env bun
-/**
- * `bun run promote --target plugin-<id>` (02 §3.3).
- *
- * Dry run by default, and loudly so: promotion is ONE-WAY, and an operator who
- * has to type `--apply` has necessarily read the plan.
- *
- * ## Status: LIBRARY-ONLY, and UNUSED in this repo (de-claimed 03 §4 / owner
- * decision E5, 2026-07-26)
- *
- * This CLI promotes a package out of a `staging/` tree into an engine feature.
- * **Nothing in cursed-core calls it, and there is no `staging/` consumer here.**
- * It ships for a downstream repo that has one; treat it as a published library
- * entry point, not as part of this repo's gate chain. Do not add it to `done`.
- *
- * Two claims were removed rather than built, because a pipeline that describes
- * work it does not do is worse than one that admits the gap:
- *
- *   * **`--migrate-check` was a PHANTOM FLAG.** The old header documented it as
- *     reporting "whether the caller supplied a migration", and `parseArgs` had no
- *     case for it — passing it did nothing at all, silently, while the docstring
- *     told an operator their DDL step had been checked. It is gone.
- *   * **The Offline Migration Routine (`runOfflineMigration`, cwip
- *     `services/sqlite/offlineMigration.ts`) is still deliberately NOT wired.**
- *     It needs the registry handle and the domain path, which belong to the app
- *     being promoted into, not to this CLI. Wiring it against a staging consumer
- *     that does not exist would be a third half-build; when a real one appears,
- *     it supplies those handles and calls the routine itself.
- *
- * So: a promotion run here moves FILES and reports a plan. It makes no claim
- * about schema migration, and it no longer pretends to offer a check for one.
- */
-import { nodePromotionFileSystem } from '../nodePromotionFs';
-import { planPromotion, runPromotion, type StagingPackageManifest } from '../promote';
-import type { EngineId } from '../../../config/appConfig';
-
-interface Args {
-  target?: string;
-  stagingRoot: string;
-  destination?: string;
-  engine?: string;
-  featureKey?: string;
-  scanRoots: string[];
-  apply: boolean;
-  json: boolean;
-}
-
-const parseArgs = (argv: readonly string[]): Args => {
-  const args: Args = { stagingRoot: 'staging', scanRoots: [], apply: false, json: false };
-  for (let i = 0; i < argv.length; i++) {
-    const flag = argv[i];
-    const value = argv[i + 1];
-    switch (flag) {
-      case '--target':
-        args.target = value;
-        i++;
-        break;
-      case '--staging-root':
-        args.stagingRoot = value ?? args.stagingRoot;
-        i++;
-        break;
-      case '--destination':
-        args.destination = value;
-        i++;
-        break;
-      case '--engine':
-        args.engine = value;
-        i++;
-        break;
-      case '--feature-key':
-        args.featureKey = value;
-        i++;
-        break;
-      case '--scan':
-        if (value) args.scanRoots.push(value);
-        i++;
-        break;
-      case '--apply':
-        args.apply = true;
-        break;
-      case '--json':
-        args.json = true;
-        break;
-      default:
-        break;
-    }
-  }
-  return args;
-};
-
-const usage = `usage: cc-promote --target plugin-<id> --engine <asset|knowledge|dev|guard|system> \\
-                  --feature-key <flag> --destination <engine package dir>
-                  [--staging-root staging] [--scan <dir> ...] [--apply] [--json]
-
-Dry run unless --apply. Promotion is one-way.`;
-
-const main = (): number => {
-  const args = parseArgs(process.argv.slice(2));
-  if (!args.target || !args.engine || !args.featureKey || !args.destination) {
-    console.error(usage);
-    return 2;
-  }
-
-  const manifest: StagingPackageManifest = {
-    id: args.target,
-    targetEngine: args.engine as EngineId,
-    featureKey: args.featureKey,
-  };
-  const options = {
-    fs: nodePromotionFileSystem,
-    manifest,
-    stagingDir: `${args.stagingRoot}/${args.target}`,
-    destinationDir: args.destination,
-    scanRoots: args.scanRoots,
-    apply: args.apply,
-  };
-
-  try {
-    if (!args.apply) {
-      const plan = planPromotion(options);
-      if (args.json) console.log(JSON.stringify(plan, null, 2));
-      else {
-        console.log(`cc-promote: DRY RUN for ${plan.pluginId} → ${plan.targetEngine}.features.${plan.featureKey}`);
-        console.log(`  ${plan.files.length} file(s) → ${plan.destinationDir}`);
-        for (const rename of plan.tokenRenames) console.log(`  token ${rename.from} → ${rename.to}`);
-        console.log('  run again with --apply to perform it (one-way).');
-        console.log('  NOTE: the Offline Migration Routine is not run by this CLI — wire runOfflineMigration');
-        console.log('        in the app being promoted into, BEFORE applying (01 §5.4).');
-      }
-      return 0;
-    }
-
-    const result = runPromotion(options);
-    if (args.json) console.log(JSON.stringify(result, null, 2));
-    else {
-      console.log(`cc-promote: promoted ${result.plan.pluginId} → ${result.plan.targetEngine}`);
-      console.log(`  moved ${result.moved.length} file(s), rewrote tokens in ${result.rewritten.length}`);
-    }
-    return 0;
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(`cc-promote: ${message}`);
-    return 1;
-  }
-};
-
-process.exit(main());

package/src/verify/promotion/index.ts

@@ -1,14 +0,0 @@
-// Promotion (02 §3.3, 01 §5.4) — the only path from `/staging` to production.
-export { nodePromotionFileSystem } from './nodePromotionFs';
-export {
-  planPromotion,
-  type PromotionFileSystem,
-  type PromotionOptions,
-  type PromotionPlan,
-  type PromotionResult,
-  rewriteTokenIds,
-  runPromotion,
-  shortId,
-  type StagingPackageManifest,
-  type TokenRename,
-} from './promote';