@12ui/design 0.2.55 → 0.2.57

package/dist/improve-kit-stall.js

@@ -0,0 +1,311 @@
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { formatDuration } from './cli-progress.js';
+import { readImproveKitAssets } from './improve-kit-assets.js';
+import { IMPROVE_NO_APPROXIMATION_RULE, IMPROVE_STALL_RESOLVED_HEADING, improveRecoveryLine, readImproveKitStatus, shellArg, } from './improve-kit-status.js';
+import { improveConversionIdFromText, improveErrorText, improveResumeConversion, } from './improve-convert-resilience.js';
+import { renderImproveRasterLayers } from './improve-raster-layers-section.js';
+import { improveAbandonedLines } from './improve-reset.js';
+import { readRunJournal } from './run-journal.js';
+import { improvePaths } from './improve-workspace.js';
+/**
+ * A stalled run still writes a plan directory.
+ *
+ * Pipedrive's conversion sat in `materializing_assets` for sixteen minutes and
+ * never journalled a terminal event, so the kit had an empty `target/`, no
+ * `plan/`, and nothing at all telling the lane what to do. It hand-authored the
+ * hero in CSS. This file is what should have been there instead: which stage,
+ * how long it waited, the hosted run id, what exists, and the three commands
+ * that recover — plus the raster layers, whenever a LayerDoc survived.
+ */
+const UUID = /[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}/iu;
+/**
+ * What the run was waiting on, from the journal it kept writing plus the error
+ * that ended the local process. The journal is authoritative for elapsed time
+ * because the error text carries none.
+ */
+export const collectImproveStallFacts = async (args) => {
+    const text = improveErrorText(args.error);
+    const entries = args.entries
+        ?? (await readRunJournal({ workspace: args.record.runDir }).catch(() => ({ entries: [] }))).entries;
+    const progress = [...entries].reverse().find((entry) => (entry.event === 'progress' && entry.paid && entry.elapsed_seconds !== undefined));
+    const journalled = [...entries].reverse().find((entry) => (entry.paid && typeof entry.run_id === 'string' && UUID.test(entry.run_id)))?.run_id;
+    const recorded = args.record.convert?.sourceConversionId;
+    const hostedRunId = args.inFlight
+        ? journalled ?? improveConversionIdFromText(text) ?? recorded
+        : recorded ?? improveConversionIdFromText(text) ?? journalled;
+    const resume = improveResumeConversion(args.record);
+    // An attempt whose id never reached the record, named from the journal
+    // instead. It is the same conversion: the open attempt is what THIS
+    // invocation dispatched, and `inFlight` is what makes the journal's newest
+    // paid line this invocation's own heartbeat rather than an earlier run's.
+    const named = resume && !resume.id && args.inFlight && hostedRunId
+        ? { ...resume, id: hostedRunId }
+        : resume;
+    return {
+        stage: args.stage,
+        kind: args.kind ?? 'stalled',
+        ...(hostedRunId ? { hostedRunId } : {}),
+        ...(named ? { resume: named } : {}),
+        ...(progress?.elapsed_seconds === undefined ? {} : { waitedSeconds: progress.elapsed_seconds }),
+        ...(progress?.typical_seconds === undefined ? {} : { typicalSeconds: progress.typical_seconds }),
+        ...(progress?.stage ? { serviceStage: progress.stage } : {}),
+        reason: text.split('\n')[0]?.trim() || 'The stage ended without settling.',
+    };
+};
+const targetContents = (status) => {
+    if (!status.present.layerDoc)
+        return 'nothing';
+    if (!status.present.assets)
+        return 'the LayerDoc only';
+    return status.present.targetHtml
+        ? 'the LayerDoc, its assets, and target HTML'
+        : 'the LayerDoc and its assets';
+};
+/**
+ * Which conversion the recovery command below actually reaches, and — when this
+ * run was watching a different one — that the one it was watching is gone.
+ *
+ * A `--fresh` or retry conversion is recorded by its exact key before it is
+ * dispatched (`improve-conversion-attempts.ts`), so a run stopped inside one
+ * resumes onto the conversion it was actually watching. The "cannot be
+ * resumed" line survives for kits written before that ledger: they hold two
+ * conversions, the base-key one `--fresh` rotated away from, which the resume
+ * lands back on, and the fresh one dispatched under a one-off nonce nothing
+ * recorded. Naming only the second reads as "resume and you get this back",
+ * which is false and costs a conversion when the reader buys another instead.
+ */
+const resumeLines = (facts) => {
+    if (!facts.resume)
+        return [];
+    const reaches = facts.resume.reason === 'settled'
+        ? 'the first command below replays it and buys nothing'
+        : 'the first command below rebuilds this kit\'s conversion key and re-attaches to it,'
+            + ' rather than buying another';
+    const lines = [
+        facts.resume.id
+            ? `- Resume attaches to: \`${facts.resume.id}\` — ${reaches}`
+            : '- Resume attaches to: the conversion this kit dispatched under its recorded key —'
+                + ' it never reported an id, but the key is on the record, so'
+                + ` ${reaches}`,
+    ];
+    if (facts.resume.reason === 'fresh-rotated-away'
+        && facts.hostedRunId
+        && facts.hostedRunId !== facts.resume.id) {
+        lines.push(`- Cannot be resumed: \`${facts.hostedRunId}\` — this run dispatched it under a one-off`
+            + ' `--fresh` key that nothing durable records, so no later command can re-attach to it.'
+            + ' It keeps running and keeps billing.');
+    }
+    return lines;
+};
+/**
+ * What a recovered run owes its reader: what stalled, what shipped instead, and
+ * how to collect the stalled half later without buying anything.
+ *
+ * `12ui resume` collects an existing purchase — it never retries, reconfigures
+ * or creates — so it is the only honest way to offer the responsive export a
+ * lane already paid for. The kit itself needs no re-run: the plan is built.
+ */
+const fallbackLines = (facts, runDir) => [
+    '',
+    '## What shipped instead',
+    '',
+    '- The fixed-layout HTML derived free from the same conversion, and the plan was built from'
+        + ' that derivation. It is not a responsive deliverable.',
+    '- The LayerDoc and its assets are unaffected: they are the full-quality source of truth and'
+        + ' the plan anchors to them.',
+    '- Nothing here needs re-running, and nothing was bought twice.',
+    '',
+    '## Recovery',
+    '',
+    'If the responsive export completes later, collect it. `resume` recovers an existing purchase;'
+        + ' it never retries, reconfigures, or creates a conversion, so it buys nothing:',
+    '',
+    ...(facts.hostedRunId
+        ? [`    12ui resume ${facts.hostedRunId} --out-dir ${shellArg(path.join(runDir, 'target'))}`]
+        : ['    12ui resume <conversion-id> --out-dir <kit>/target']),
+    '',
+];
+export const renderImproveStall = (args) => {
+    const waited = args.facts.waitedSeconds === undefined
+        ? 'unrecorded'
+        : `${formatDuration(args.facts.waitedSeconds)}`
+            + `${args.facts.boundSeconds === undefined
+                ? ''
+                : ` (bound ${formatDuration(args.facts.boundSeconds)})`}`
+            + `${args.facts.typicalSeconds === undefined
+                ? ''
+                : ` against a typical ${formatDuration(args.facts.typicalSeconds)}`}`;
+    const fallback = args.facts.kind === 'fallback';
+    const lines = [
+        // A recovered run is not INCOMPLETE — the kit is whole and the plan is
+        // built — so it must not lead with the word that tells a lane to stop and
+        // resume. It still leads with what stalled, because that is the fact the
+        // summary, the README and this file all have to agree on (F8).
+        fallback
+            ? '# Responsive export stalled — plan from the fixed-layout fallback'
+            : `# INCOMPLETE — this run ${args.facts.kind === 'stopped' ? 'was stopped' : 'stalled'}`,
+        '',
+        `- Stage: ${args.facts.stage}${fallback ? ' (responsive export)' : ''}`
+            + `${args.facts.serviceStage ? ` (service stage \`${args.facts.serviceStage}\`)` : ''}`,
+        `- Waited: ${waited}`,
+        `- Hosted run: ${args.facts.hostedRunId ? `\`${args.facts.hostedRunId}\`` : 'not recorded'}`,
+        ...(fallback ? [] : resumeLines(args.facts)),
+        `- In \`target/\`: ${targetContents(args.status)}`,
+        `- Reason: ${args.facts.reason}`,
+        ...improveAbandonedLines(args.record),
+        ...(fallback ? fallbackLines(args.facts, args.record.runDir) : [
+            '',
+            '## Recovery',
+            '',
+            'Run the first command; it resumes and replays every settled stage rather than buying them again.',
+            '',
+            ...args.status.recovery.map(improveRecoveryLine),
+            // The conversion this run was waiting on is still running and still
+            // billing, and improve bought nothing to replace it (F19). `resume`
+            // collects it — it never retries, reconfigures or creates — so it is the
+            // second thing to reach for, ahead of any command that converts again.
+            ...(args.facts.hostedRunId ? [
+                '',
+                'The conversion above is still running. Collect it directly once it finishes;'
+                    + ' `resume` recovers an existing purchase and buys nothing:',
+                '',
+                `    12ui resume ${args.facts.hostedRunId}`
+                    + ` --out-dir ${shellArg(path.join(args.record.runDir, 'target'))}`,
+            ] : []),
+            '',
+            // Only for a kit that is actually missing something. Telling a complete
+            // fallback kit to "resume or convert first" would send a lane to buy the
+            // conversion it already has.
+            IMPROVE_NO_APPROXIMATION_RULE,
+            '',
+        ]),
+    ];
+    if (args.status.present.layerDoc) {
+        lines.push(
+        // What the LayerDoc makes available, in the words the README uses for the
+        // same fact (F22). "Usable without a plan" read as permission to build
+        // the page without one, three lines under a rule that forbids exactly
+        // that; the boundary now lives in one place and both files print it.
+        'A LayerDoc survived this run, so the design\'s raster layers are already extracted.'
+            + ' They are files: carry them.', '', ...renderImproveRasterLayers({ layers: args.index.rasterLayers }));
+    }
+    return lines.join('\n');
+};
+/**
+ * The same file, for the run that recovered.
+ *
+ * The facts come off the durable record rather than out of an error, because
+ * there is no error: the responsive export stalled, the free derivation took
+ * over, and the run went on to build a plan. A kit written before
+ * `responsiveStall` existed records the fallback but not its timings, so this
+ * writes what it has and never invents a number.
+ */
+export const writeImproveFallbackStall = async (args) => {
+    const convert = args.record.convert;
+    if (convert?.layout !== 'fixed')
+        return undefined;
+    const paths = improvePaths(args.record.runDir);
+    const stall = convert.responsiveStall;
+    const facts = {
+        stage: 'convert',
+        kind: 'fallback',
+        ...(stall?.conversionId ?? convert.sourceConversionId
+            ? { hostedRunId: stall?.conversionId ?? convert.sourceConversionId }
+            : {}),
+        ...(stall ? { waitedSeconds: stall.waitedSeconds, boundSeconds: stall.boundSeconds } : {}),
+        reason: convert.responsiveWarning ?? 'Responsive HTML was unavailable.',
+    };
+    const [status, index] = await Promise.all([
+        readImproveKitStatus({
+            record: args.record,
+            ...(args.requestedTo ? { requestedTo: args.requestedTo } : {}),
+        }),
+        readImproveKitAssets({ runDir: args.record.runDir, layerDocPath: paths.targetLayerDoc }),
+    ]);
+    await mkdir(paths.planDir, { recursive: true });
+    const file = path.join(paths.planDir, 'STALL.md');
+    await writeFile(file, renderImproveStall({ record: args.record, facts, status, index }), 'utf8');
+    return file;
+};
+const stalledStageFrom = (content) => (/^- Stage: ([a-z]+)/mu.exec(content)?.[1]);
+/**
+ * The stall this kit recorded is over, so the file that recorded it stops
+ * saying the kit is INCOMPLETE (F21).
+ *
+ * Freshdesk's `--from convert` resume settled at 18:56:41Z and wrote a whole
+ * plan; the `plan/STALL.md` from 18:48:17Z survived beside it, still saying
+ * "this run was stopped", "no plan", and "resume or convert first" — directly
+ * contradicting the README above it, which said the plan was settled. A reader
+ * opening that kit cold got two mutually exclusive statuses and no way to tell
+ * which was current.
+ *
+ * The file is REPLACED rather than deleted: it is the durable record that this
+ * kit stalled once, which is worth keeping, and a README that links to it must
+ * not link to nothing. Its mtime is when the stall was written, which is the
+ * one timestamp neither the record nor the journal keeps.
+ */
+export const resolveImproveStall = async (args) => {
+    // Only once every stage this kit was asked for has settled. A `--to pick`
+    // run, or one that stalled again, leaves the file standing because it is
+    // still true.
+    if (!args.status.present.stall)
+        return undefined;
+    if (args.status.stages.some((stage) => stage.state === 'incomplete'))
+        return undefined;
+    // A fallback kit's STALL.md is rewritten by `writeImproveFallbackStall` every
+    // run and describes a stall that is not over: the responsive export never
+    // arrived, and the recovery it offers still collects it.
+    if (args.record.convert?.layout === 'fixed')
+        return undefined;
+    const file = path.join(improvePaths(args.record.runDir).planDir, 'STALL.md');
+    const [content, stalledAt] = await Promise.all([
+        readFile(file, 'utf8').catch(() => undefined),
+        stat(file).then((entry) => entry.mtime).catch(() => undefined),
+    ]);
+    if (content === undefined)
+        return undefined;
+    if (content.startsWith(IMPROVE_STALL_RESOLVED_HEADING))
+        return file;
+    const stage = stalledStageFrom(content);
+    await writeFile(file, [
+        IMPROVE_STALL_RESOLVED_HEADING,
+        '',
+        `- Stalled at: ${stalledAt ? stalledAt.toISOString() : 'unrecorded'}`
+            + `${stage ? ` (stage ${stage})` : ''}`,
+        `- Resumed and settled at: ${(args.now ?? new Date()).toISOString()}`,
+        '- Every stage this kit was asked for has settled since. The plan and the target'
+            + ' beside this file are current, and nothing here needs re-running.',
+        '',
+        'This file is kept as the record that the run stalled once. `README.md` has the'
+            + ' kit\'s status, and `plan/plan-annotated.md` has the work.',
+        '',
+    ].join('\n'), 'utf8');
+    return file;
+};
+/**
+ * Write `plan/STALL.md`, creating `plan/` when the plan stage never ran.
+ * Returns the file so the caller can journal it as an artifact.
+ */
+export const writeImproveStallReport = async (args) => {
+    const paths = improvePaths(args.record.runDir);
+    const [facts, status, index] = await Promise.all([
+        collectImproveStallFacts({
+            record: args.record,
+            stage: args.stage,
+            error: args.error,
+            ...(args.kind ? { kind: args.kind } : {}),
+            ...(args.inFlight === undefined ? {} : { inFlight: args.inFlight }),
+        }),
+        readImproveKitStatus({
+            record: args.record,
+            ...(args.requestedTo ? { requestedTo: args.requestedTo } : {}),
+        }),
+        readImproveKitAssets({ runDir: args.record.runDir, layerDocPath: paths.targetLayerDoc }),
+    ]);
+    await mkdir(paths.planDir, { recursive: true });
+    const file = path.join(paths.planDir, 'STALL.md');
+    await writeFile(file, renderImproveStall({ record: args.record, facts, status, index }), 'utf8');
+    return file;
+};
+//# sourceMappingURL=improve-kit-stall.js.map

package/dist/improve-kit-stall.js.map

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

package/dist/improve-kit-status.d.ts

@@ -0,0 +1,105 @@
+import { type ImproveRecord, type ImproveStage } from './improve-workspace.js';
+/**
+ * One honest reading of "how far did this kit actually get".
+ *
+ * Read from the durable record AND the filesystem, because the record only
+ * ever describes stages that settled: a run killed inside `materializing_assets`
+ * leaves a record that says capture, draft and pick are fine and says nothing
+ * at all about the empty `target/` the reader is looking at.
+ */
+export type ImproveStageState = 'settled' | 'replayed' | 'skipped' | 'fallback' | 'blocked' | 'incomplete' | 'not-requested';
+export type ImproveStageStatus = {
+    stage: ImproveStage;
+    state: ImproveStageState;
+    detail?: string;
+};
+export type ImproveTargetMode = 'responsive HTML' | 'fixed-layout fallback' | 'LayerDoc only' | 'none';
+/** One recovery command and what running it costs. */
+export type ImproveRecoveryCommand = {
+    command: string;
+    spends: string;
+};
+export type ImproveKitStatus = {
+    stages: ImproveStageStatus[];
+    /** Every requested stage settled and the artifacts it promises are on disk. */
+    complete: boolean;
+    /**
+     * The coverage gate blocked the anchored plan, so `plan/GATE.md` replaced
+     * `plan-annotated.md` and `token-patch.css`. Nothing is missing and nothing
+     * stalled: it is a third outcome, and a reader sent to files the gate deleted
+     * is a reader who gives up on the kit.
+     */
+    gateBlocked: boolean;
+    /** What a reader will not find, in the words the recovery commands answer. */
+    missing: string[];
+    targetMode: ImproveTargetMode;
+    present: {
+        design: boolean;
+        layerDoc: boolean;
+        assets: boolean;
+        targetHtml: boolean;
+        plan: boolean;
+        gate: boolean;
+        stall: boolean;
+        /** The `STALL.md` present is the record of a stall that has since settled. */
+        stallResolved: boolean;
+    };
+    /** The file a reader should look at and a conversion can be re-run from. */
+    designImage: string;
+    /** A supplied `*.layerdoc.json` target kit has a document, not a picture. */
+    designKind: 'image' | 'layerdoc';
+    recovery: ImproveRecoveryCommand[];
+};
+/**
+ * The heading a `plan/STALL.md` leads with once the stall it recorded has
+ * settled. It lives here rather than beside the renderer because the kit
+ * status has to be able to tell a live stall from a resolved one without
+ * importing the renderer that writes it.
+ */
+export declare const IMPROVE_STALL_RESOLVED_HEADING = "# Resolved \u2014 the stall recorded here has settled";
+/**
+ * THE ONE BOUNDARY SENTENCE, and the reason it is one sentence in one module.
+ *
+ * The README and `plan/STALL.md` shipped together and disagreed (F22). The
+ * README said "do not approximate the design in CSS from the PNG while a stage
+ * is incomplete"; three lines further down STALL.md said "a LayerDoc survived
+ * this run, so the design's raster layers are usable without a plan". Both are
+ * true of different things — carry the rasters, do not redraw the layout — but
+ * nothing in the kit said so, and a lane had to adjudicate the contradiction
+ * itself, after both of its conversions were already spent. Every renderer
+ * prints this string; none writes its own version of it.
+ */
+export declare const IMPROVE_NO_APPROXIMATION_RULE: string;
+/**
+ * A recovery command is presented as copy-and-run, so it has to survive being
+ * pasted. Capture URLs carry query strings and `--out-dir` paths carry spaces;
+ * either one unquoted breaks the line or backgrounds it at the `&`.
+ */
+export declare const shellArg: (value: string) => string;
+/**
+ * The draw is ready and nobody has chosen.
+ *
+ * `--pick` has no default, so a run with candidates and no pick is a finished
+ * run holding a drafts-only kit — not a stall. It is the one incomplete state
+ * whose recovery is neither a resume nor a conversion.
+ */
+export declare const improveAwaitingPick: (record: ImproveRecord) => boolean;
+/**
+ * The `--pick` placeholder, in one place, so the run summary and the kit README
+ * cannot drift into naming different slots for the same draw.
+ */
+export declare const improvePickSlotHint: (record: ImproveRecord) => string;
+/** The one sentence a never-picked kit needs before its recovery command. */
+export declare const IMPROVE_AWAITING_PICK_RULE: string;
+export declare const improveRecoveryCommands: (args: {
+    record: ImproveRecord;
+    designImage: string;
+}) => ImproveRecoveryCommand[];
+/** One indented, copy-pasteable line; the cost rides along as a shell comment. */
+export declare const improveRecoveryLine: (entry: ImproveRecoveryCommand) => string;
+export declare const readImproveKitStatus: (args: {
+    record: ImproveRecord;
+    requestedTo?: ImproveStage;
+}) => Promise<ImproveKitStatus>;
+export declare const improveStageStatusLine: (status: ImproveStageStatus) => string;
+//# sourceMappingURL=improve-kit-status.d.ts.map

package/dist/improve-kit-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"improve-kit-status.d.ts","sourceRoot":"","sources":["../src/improve-kit-status.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgC,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE7G;;;;;;;GAOG;AAEH,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,UAAU,GACV,SAAS,GACT,UAAU,GACV,SAAS,GACT,YAAY,GACZ,eAAe,CAAC;AAEpB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,uBAAuB,GACvB,eAAe,GACf,MAAM,CAAC;AAEX,sDAAsD;AACtD,MAAM,MAAM,sBAAsB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,OAAO,EAAE;QACP,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;QACpB,IAAI,EAAE,OAAO,CAAC;QACd,IAAI,EAAE,OAAO,CAAC;QACd,KAAK,EAAE,OAAO,CAAC;QACf,8EAA8E;QAC9E,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,EAAE,OAAO,GAAG,UAAU,CAAC;IACjC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC,CAAC;AA8DF;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,0DAAqD,CAAC;AAEjG;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,QAE2C,CAAC;AAEtF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,KAAG,MAExC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,aAAa,KAAG,OAE3D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,aAAa,KAAG,MAG3D,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,0BAA0B,QAEoC,CAAC;AAE5E,eAAO,MAAM,uBAAuB,GAAI,MAAM;IAC5C,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,sBAAsB,EA8BzB,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,GAAI,OAAO,sBAAsB,KAAG,MAEnE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,MAAM;IAC/C,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B,KAAG,OAAO,CAAC,gBAAgB,CAmF3B,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,QAAQ,kBAAkB,KAAG,MAGnE,CAAC"}

package/dist/improve-kit-status.js

@@ -0,0 +1,215 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { IMPROVE_STAGES, improvePaths } from './improve-workspace.js';
+const isFile = async (file) => Boolean(await stat(file).then((entry) => entry.isFile()).catch(() => false));
+const isDirectory = async (file) => Boolean(await stat(file).then((entry) => entry.isDirectory()).catch(() => false));
+const stageState = (args) => {
+    const settled = args.record.stages[args.stage];
+    if (!settled) {
+        return IMPROVE_STAGES.indexOf(args.stage) > IMPROVE_STAGES.indexOf(args.requestedTo)
+            ? { stage: args.stage, state: 'not-requested', detail: 'outside the requested stage range' }
+            : { stage: args.stage, state: 'incomplete' };
+    }
+    if (settled.outcome === 'skipped') {
+        return { stage: args.stage, state: 'skipped', detail: 'a target was supplied' };
+    }
+    // Recorded at dispatch and never settled (F19). The entry exists so the kit
+    // can price the paid call it is still owed a result for; it is not evidence
+    // the stage ran, and reading it as one would call a stalled kit settled.
+    // `stalled` is the same entry after the run gave up on it (F28) — still
+    // incomplete, and still the stage `plan/STALL.md` is about.
+    if (settled.outcome === 'dispatched' || settled.outcome === 'stalled') {
+        return {
+            stage: args.stage,
+            state: 'incomplete',
+            detail: settled.outcome === 'stalled'
+                ? 'a paid call was dispatched and stalled; read `plan/STALL.md`'
+                : 'a paid call was dispatched and has not settled; read `plan/STALL.md`',
+        };
+    }
+    if (args.blocked) {
+        return {
+            stage: args.stage,
+            state: 'blocked',
+            detail: 'the coverage gate blocked the anchored plan; read `plan/GATE.md`',
+        };
+    }
+    if (!args.delivered)
+        return { stage: args.stage, state: 'incomplete', detail: 'recorded, but its files are not in the kit' };
+    if (args.stage === 'convert' && args.record.convert?.layout === 'fixed') {
+        return {
+            stage: 'convert',
+            state: 'fallback',
+            detail: args.record.convert.responsiveWarning ?? 'Responsive HTML was unavailable.',
+        };
+    }
+    return {
+        stage: args.stage,
+        state: settled.replayCount > 0 ? 'replayed' : 'settled',
+        ...(settled.replayCount > 0 ? { detail: `replayed ${settled.replayCount}×, bought once` } : {}),
+    };
+};
+/**
+ * The heading a `plan/STALL.md` leads with once the stall it recorded has
+ * settled. It lives here rather than beside the renderer because the kit
+ * status has to be able to tell a live stall from a resolved one without
+ * importing the renderer that writes it.
+ */
+export const IMPROVE_STALL_RESOLVED_HEADING = '# Resolved — the stall recorded here has settled';
+/**
+ * THE ONE BOUNDARY SENTENCE, and the reason it is one sentence in one module.
+ *
+ * The README and `plan/STALL.md` shipped together and disagreed (F22). The
+ * README said "do not approximate the design in CSS from the PNG while a stage
+ * is incomplete"; three lines further down STALL.md said "a LayerDoc survived
+ * this run, so the design's raster layers are usable without a plan". Both are
+ * true of different things — carry the rasters, do not redraw the layout — but
+ * nothing in the kit said so, and a lane had to adjudicate the contradiction
+ * itself, after both of its conversions were already spent. Every renderer
+ * prints this string; none writes its own version of it.
+ */
+export const IMPROVE_NO_APPROXIMATION_RULE = 'Once the LayerDoc exists, carry its raster layers as'
+    + ' real assets — copy the files and reference them. Do not approximate the design\'s layout or'
+    + ' text in CSS from the PNG while a stage is incomplete; resume or convert first.';
+/**
+ * A recovery command is presented as copy-and-run, so it has to survive being
+ * pasted. Capture URLs carry query strings and `--out-dir` paths carry spaces;
+ * either one unquoted breaks the line or backgrounds it at the `&`.
+ */
+export const shellArg = (value) => (/^[A-Za-z0-9_./:=-]+$/u.test(value) ? value : `'${value.replace(/'/gu, "'\\''")}'`);
+/**
+ * The draw is ready and nobody has chosen.
+ *
+ * `--pick` has no default, so a run with candidates and no pick is a finished
+ * run holding a drafts-only kit — not a stall. It is the one incomplete state
+ * whose recovery is neither a resume nor a conversion.
+ */
+export const improveAwaitingPick = (record) => (!record.pick && !record.target && (record.draft?.candidates.length ?? 0) > 0);
+/**
+ * The `--pick` placeholder, in one place, so the run summary and the kit README
+ * cannot drift into naming different slots for the same draw.
+ */
+export const improvePickSlotHint = (record) => {
+    const slots = (record.draft?.candidates ?? []).map((candidate) => candidate.slot);
+    return `<A-${slots.at(-1) ?? 'P'}>`;
+};
+/** The one sentence a never-picked kit needs before its recovery command. */
+export const IMPROVE_AWAITING_PICK_RULE = 'The draw is ready and nothing has been picked.'
+    + ' The CLI stops after drafting by design: nothing is converted until you choose a candidate,'
+    + ' because converting a candidate nobody chose spends money on a guess.';
+export const improveRecoveryCommands = (args) => {
+    const runDir = shellArg(args.record.runDir);
+    const input = shellArg(args.record.input.value);
+    const design = shellArg(args.designImage);
+    // A never-picked kit has no winner, so `designImage` falls back to the
+    // capture — the page the run was asked to improve. The three commands below
+    // all resolve to it, so offering them here sent a reader to buy a conversion
+    // of the page they were improving. The pick is this state's only recovery.
+    if (improveAwaitingPick(args.record)) {
+        return [{
+                command: `12ui improve ${input} --out-dir ${runDir}`
+                    + ` --from pick --pick ${improvePickSlotHint(args.record)}`,
+                spends: 'picks a candidate, then buys its conversion and plan',
+            }];
+    }
+    return [
+        {
+            command: `12ui improve ${input} --out-dir ${runDir} --from convert`,
+            spends: 'resumes; settled stages replay',
+        },
+        { command: `12ui convert ${design} --output html`, spends: 'buys one conversion' },
+        // `--target` is documented against a URL input. Offering it for an image
+        // input would name a mode the CLI does not document.
+        ...(args.record.input.kind === 'url'
+            ? [{
+                    command: `12ui improve ${input} --target ${design}`,
+                    spends: 'buys one fused target conversion',
+                }]
+            : []),
+    ];
+};
+/** One indented, copy-pasteable line; the cost rides along as a shell comment. */
+export const improveRecoveryLine = (entry) => (`    ${entry.command}  # ${entry.spends}`);
+export const readImproveKitStatus = async (args) => {
+    const paths = improvePaths(args.record.runDir);
+    const requestedTo = args.requestedTo ?? IMPROVE_STAGES[IMPROVE_STAGES.length - 1];
+    const [winner, sourceImage, layerDoc, assets, plan, gate, stall] = await Promise.all([
+        isFile(paths.winnerImage),
+        isFile(paths.sourceImage),
+        isFile(paths.targetLayerDoc),
+        isDirectory(`${paths.targetLayerDoc}.assets`),
+        isFile(path.join(paths.planDir, 'plan-annotated.md')),
+        isFile(path.join(paths.planDir, 'GATE.md')),
+        isFile(path.join(paths.planDir, 'STALL.md')),
+    ]);
+    const stallResolved = stall && (await readFile(path.join(paths.planDir, 'STALL.md'), 'utf8')
+        .then((content) => content.startsWith(IMPROVE_STALL_RESOLVED_HEADING))
+        .catch(() => false));
+    const recordedHtml = args.record.convert?.html;
+    const targetHtml = recordedHtml ? await isFile(recordedHtml) : await isFile(paths.targetHtml);
+    // Name a file that is actually here. A `--target <layerdoc>` kit never gets a
+    // winner.png, and a run that stalled before pick has only its capture.
+    const captured = args.record.capture?.sourceImage;
+    const designImage = winner
+        ? paths.winnerImage
+        : sourceImage
+            ? paths.sourceImage
+            : captured && await isFile(captured)
+                ? captured
+                : layerDoc && args.record.target?.kind === 'layerdoc'
+                    ? paths.targetLayerDoc
+                    : paths.winnerImage;
+    const designKind = designImage === paths.targetLayerDoc ? 'layerdoc' : 'image';
+    const delivered = {
+        capture: Boolean(args.record.capture),
+        draft: Boolean(args.record.draft),
+        pick: Boolean(args.record.pick),
+        convert: layerDoc,
+        plan: plan || gate,
+    };
+    const gateBlocked = gate && !plan;
+    const stages = IMPROVE_STAGES.map((stage) => stageState({
+        record: args.record,
+        stage,
+        requestedTo,
+        delivered: delivered[stage],
+        blocked: stage === 'plan' && gateBlocked,
+    }));
+    const targetMode = !layerDoc
+        ? 'none'
+        : args.record.convert?.layout === 'fixed'
+            ? 'fixed-layout fallback'
+            : targetHtml ? 'responsive HTML' : 'LayerDoc only';
+    // Only stages the caller actually asked for can be missing. `--to pick` is a
+    // finished run, not an incomplete one.
+    const owed = (stage) => (IMPROVE_STAGES.indexOf(stage) <= IMPROVE_STAGES.indexOf(requestedTo));
+    // A supplied `*.layerdoc.json` target buys no conversion, so it owes neither
+    // extracted assets nor target HTML: naming them missing would be a false alarm.
+    const suppliedDocument = args.record.target?.kind === 'layerdoc';
+    const convertOwed = owed('convert') && !suppliedDocument;
+    const missing = [
+        ...(!owed('convert') || layerDoc ? [] : ['no LayerDoc']),
+        ...(!convertOwed || assets ? [] : ['no assets']),
+        ...(!convertOwed || targetHtml ? [] : ['no target HTML']),
+        ...(!owed('plan') || plan || gate ? [] : ['no plan']),
+    ];
+    const complete = stages.every((entry) => entry.state !== 'incomplete') && missing.length === 0;
+    return {
+        stages,
+        complete,
+        gateBlocked,
+        missing,
+        targetMode,
+        present: {
+            design: winner || sourceImage, layerDoc, assets, targetHtml, plan, gate, stall, stallResolved,
+        },
+        designImage,
+        designKind,
+        recovery: improveRecoveryCommands({ record: args.record, designImage }),
+    };
+};
+export const improveStageStatusLine = (status) => {
+    const label = status.state === 'incomplete' ? 'INCOMPLETE' : status.state;
+    return `${status.stage}: ${label}${status.detail ? ` — ${status.detail}` : ''}`;
+};
+//# sourceMappingURL=improve-kit-status.js.map