@plaintake/scenario 1.14.0 → 1.23.0

package/dist/index.js

@@ -838,6 +838,31 @@ var RenderPlanSchema = z6.object({
    * older binary's own re-parse has stripped `theme` out of.
    */
   theme: ThemeSchema.optional(),
+  /**
+   * The one video this plan renders to, named for the scenario: `output/create-api-key.mp4`
+   * for `id: 'create-api-key'`. Frozen once, at record time, from the scenario's own id —
+   * `ScenarioMetaSchema`'s lowercase-kebab id rule is what the path regex above mirrors, so
+   * the two cannot drift apart silently.
+   *
+   * Optional and **never defaulted**, for the same reason as `theme`: a Zod `.default()`
+   * materialises on parse, and every parse-and-rewrite of an older plan (a `--aspect`
+   * re-cut re-freezes `render/render-plan.json`) would inject the field into bundles
+   * recorded before per-scenario names existed. Absent means exactly that — a plan frozen
+   * before 1.21, whose video is the historical `output/demo.mp4` the renderer's arg
+   * builders fall back to.
+   *
+   * Top-level — a sibling of `theme`, not a key inside `video` (which `recutPlan` rewrites
+   * wholesale) — so `recutPlan`'s `{...plan}` spread carries it through `--aspect` re-cuts
+   * unchanged.
+   *
+   * The frozen `ffmpeg` arrays remain the runtime source of truth: `renderBundle` replays
+   * them verbatim and `outputPathOf` reads the destination back out of them, which is what
+   * lets a bundle frozen under any earlier naming scheme render unchanged. This field
+   * exists for the *re*-freezes — `recutPlan` and the multi-actor splice rebuild their
+   * argument arrays from the plan, and read this field (via `outputOf`) so a re-cut writes
+   * the file the original recording wrote rather than the fallback name.
+   */
+  outputPath: z6.string().regex(/^output\/[a-z0-9][a-z0-9-]*\.mp4$/, "must be output/<scenario-id>.mp4, a kebab-case id").optional(),
   /**
    * The capture timeline cut into windows — of a genuine multi-actor cast, of an implicit
    * single actor pausing for explain cut-aways, or both at once. `segments` is the one
@@ -1036,7 +1061,14 @@ var RunCommandResultSchema = z7.object({
   narratedCount: z7.number().int().nonnegative(),
   diagnostics: z7.array(z7.object({ code: z7.string(), cueId: z7.string(), detail: z7.string() })),
   assertions: z7.array(AssertionSchema),
-  outputs: z7.array(ArtifactRefSchema)
+  outputs: z7.array(ArtifactRefSchema),
+  /**
+   * The previous bundle this run replaced, archived as a `.<timestamp>` sibling rather
+   * than deleted. Absent when nothing occupied the output directory — the common first
+   * run — or when `--no-archive` asked for the old replace semantics. Optional and
+   * additive, so every result written before archives existed still parses.
+   */
+  archivedPath: DISPLAY_PATH.optional()
 });
 var CheckAssertionSchema = AssertionSchema.extend({ message: z7.string().optional() });
 var CheckCommandResultSchema = z7.object({
@@ -1045,9 +1077,10 @@ var CheckCommandResultSchema = z7.object({
   status: StatusSchema,
   assertions: z7.array(CheckAssertionSchema),
   /**
-   * Handoff notes only. Cue, chapter, cursor and camera diagnostics are all derived from a
-   * render plan that `check` never builds — fabricating them would report on capabilities
-   * this command cannot see.
+   * Handoff notes, plus a `speech.close` note when closing the narrator failed after
+   * capture. Cue, chapter, cursor and camera diagnostics are all derived from a render plan
+   * that `check` never builds — fabricating them would report on capabilities this command
+   * cannot see.
    */
   diagnostics: z7.array(z7.object({ code: z7.string(), cueId: z7.string(), detail: z7.string() }))
 });
@@ -1082,6 +1115,17 @@ var DiffCommandResultSchema = z7.object({
   identical: z7.boolean(),
   differences: z7.array(z7.object({ category: DifferenceCategorySchema, detail: z7.string() }))
 });
+var CompareCommandResultSchema = z7.object({
+  ...envelope("compare"),
+  bundleA: DISPLAY_PATH,
+  bundleB: DISPLAY_PATH,
+  checks: z7.array(z7.object({ name: z7.string(), ok: z7.boolean(), detail: z7.string() }))
+});
+var InitResultSchema = z7.object({
+  ...envelope("init"),
+  files: z7.array(DISPLAY_PATH),
+  validates: z7.boolean()
+});
 var PruneCandidateSchema = z7.object({
   path: DISPLAY_PATH,
   bytes: z7.number().int().nonnegative(),
@@ -1326,6 +1370,51 @@ var LicenceResultSchema = z7.discriminatedUnion("tier", [
     uses: z7.number().int().nonnegative()
   })
 ]).refine(okMatchesProblems, "ok must be true iff problems is empty");
+var PublishReasonSchema = z7.enum([
+  "no-endpoint",
+  "no-key",
+  "invalid-store",
+  "not-a-bundle",
+  "unauthorized",
+  "unreachable",
+  "hash-mismatch",
+  "length-mismatch",
+  "conflict",
+  "unexpected-response"
+]);
+var PublishResultSchema = z7.discriminatedUnion("ok", [
+  z7.object({
+    ...envelope("publish"),
+    ok: z7.literal(false),
+    reason: PublishReasonSchema
+  }),
+  z7.object({
+    ...envelope("publish"),
+    ok: z7.literal(true),
+    videoId: z7.string().regex(/^[a-z2-7]{26}$/, "must be a 26-char base32 share id"),
+    /** The page viewers open — the endpoint plus the id. */
+    url: z7.string().regex(/^https?:\/\/\S+$/, "must be an http or https URL"),
+    /** False when the video was already on the service — nothing was uploaded. */
+    uploaded: z7.boolean(),
+    /**
+     * Present only when `--remember` was asked: true when the key was stored beside
+     * license.json, false when the key file could not be written. The service's
+     * proof of the key (an accepted PUT, or the identity check on an already-shared
+     * run) is part of every success, so it is never the reason.
+     */
+    remembered: z7.boolean().optional(),
+    /**
+     * The ISO-8601 instant the share link now dies at — present only when an expiry
+     * policy (`--expiry` or publish.json's `expiry`) was set. Absent means never
+     * expires, exactly like a publish before the feature existed.
+     */
+    expiresAt: z7.string().min(1).optional(),
+    captions: z7.boolean(),
+    chapters: z7.boolean(),
+    /** False is a state, not a fault: no FFmpeg on PATH means no poster frame. */
+    poster: z7.boolean()
+  })
+]).refine(okMatchesProblems, "ok must be true iff problems is empty");
 
 // ../schema/src/zod-format.ts
 import { ZodError } from "zod";

package/dist/schema/render-plan.d.ts

@@ -737,6 +737,7 @@ export declare const RenderPlanSchema: z.ZodObject<{
     theme: z.ZodOptional<z.ZodObject<{
         accentColor: z.ZodString;
     }, z.core.$strip>>;
+    outputPath: z.ZodOptional<z.ZodString>;
     actors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;

package/dist/schema/results.d.ts

@@ -47,6 +47,7 @@ export declare const RunCommandResultSchema: z.ZodObject<{
         sha256: z.ZodString;
         bytes: z.ZodNumber;
     }, z.core.$strip>>;
+    archivedPath: z.ZodOptional<z.ZodString>;
     schema: z.ZodLiteral<"agent-demo.result/v1">;
     kind: z.ZodLiteral<"run">;
     ok: z.ZodBoolean;
@@ -257,6 +258,49 @@ export declare const DiffCommandResultSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     problems: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * `compare <bundleA> <bundleB>`'s result. Two `DISPLAY_PATH`s like `diff`, because it reads two
+ * bundles — but where `diff` is a *semantic* comparison of two different recordings and drift is
+ * never a fault, `compare` is a **render-determinism gate**: it re-hashes and re-decodes two
+ * renders that should be byte-for-byte identical, so a difference is a regression. `ok` therefore
+ * IS the verdict — the renders match — and a failing check names itself in `problems`, exactly the
+ * stance `verify` takes on a hash mismatch (unlike `diff`, whose `ok` is deliberately untied from
+ * its verdict). Exit 6, reusing `verify`'s and `diff`'s code, on drift or on a bundle whose
+ * rendered output could not be read back out. `checks` mirrors `compareRenders`'s own report so a
+ * caller sees every check, not only the failing ones. CLI-only: the MCP tool list is frozen at four.
+ */
+export declare const CompareCommandResultSchema: z.ZodObject<{
+    bundleA: z.ZodString;
+    bundleB: z.ZodString;
+    checks: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        ok: z.ZodBoolean;
+        detail: z.ZodString;
+    }, z.core.$strip>>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"compare">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * `init [<name>]`'s result. The scaffold is a starting point that must validate by
+ * construction — its template pins the deterministic video contract and uses no clock,
+ * randomness, network or absolute paths — but `validates` is still reported separately from
+ * `ok`, on the same pattern as `import`'s field of the same name, because the two answer
+ * different questions: `ok` says files were written; `validates` says the generated scenario
+ * passed the same `loadScenario` validate runs. A `false` there means the template drifted
+ * from the contract, not that the command failed. `files` names everything written, relative
+ * to the working directory: the scenario plus, only when none existed, a starter
+ * `plaintake.config.json` — an existing config is never touched, so it never appears here.
+ */
+export declare const InitResultSchema: z.ZodObject<{
+    files: z.ZodArray<z.ZodString>;
+    validates: z.ZodBoolean;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"init">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 /**
  * `prune`'s result. Selection never touches disk by itself — `dryRun: true` (the default,
  * absent `--yes`) means `candidates` names what *would* be removed and every one of them is
@@ -467,6 +511,46 @@ export declare const LicenceResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     ok: z.ZodBoolean;
     problems: z.ZodArray<z.ZodString>;
 }, z.core.$strip>], "tier">;
+/**
+ * A share that either landed or did not. Discriminated on `ok` because the two halves
+ * carry disjoint facts: a failure has a `reason` to switch on, a success has the link —
+ * and a caller reading one should never have to wonder whether the other is lying.
+ *
+ * The success `videoId` is the share service's content-derived id (first 16 bytes of the
+ * MP4's sha256, base32), not a plaintake id, so its shape is asserted here rather than
+ * borrowed from a bundle schema.
+ */
+export declare const PublishResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    reason: z.ZodEnum<{
+        "unexpected-response": "unexpected-response";
+        "no-endpoint": "no-endpoint";
+        "no-key": "no-key";
+        "invalid-store": "invalid-store";
+        "not-a-bundle": "not-a-bundle";
+        unauthorized: "unauthorized";
+        unreachable: "unreachable";
+        "hash-mismatch": "hash-mismatch";
+        "length-mismatch": "length-mismatch";
+        conflict: "conflict";
+    }>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"publish">;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    videoId: z.ZodString;
+    url: z.ZodString;
+    uploaded: z.ZodBoolean;
+    remembered: z.ZodOptional<z.ZodBoolean>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    captions: z.ZodBoolean;
+    chapters: z.ZodBoolean;
+    poster: z.ZodBoolean;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"publish">;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "ok">;
 export type ArtifactRef = z.infer<typeof ArtifactRefSchema>;
 export type ValidationResult = z.infer<typeof ValidationResultSchema>;
 export type RunCommandResult = z.infer<typeof RunCommandResultSchema>;
@@ -475,13 +559,16 @@ export type RenderCommandResult = z.infer<typeof RenderCommandResultSchema>;
 export type VerificationReport = z.infer<typeof VerificationReportSchema>;
 export type WarmCommandResult = z.infer<typeof WarmCommandResultSchema>;
 export type DiffCommandResult = z.infer<typeof DiffCommandResultSchema>;
+export type CompareCommandResult = z.infer<typeof CompareCommandResultSchema>;
+export type InitResult = z.infer<typeof InitResultSchema>;
 export type PruneCommandResult = z.infer<typeof PruneCommandResultSchema>;
 export type ImportCommandResult = z.infer<typeof ImportCommandResultSchema>;
 export type InspectResult = z.infer<typeof InspectResultSchema>;
 export type DoctorResult = z.infer<typeof DoctorResultSchema>;
 export type ActivateResult = z.infer<typeof ActivateResultSchema>;
 export type LicenceResult = z.infer<typeof LicenceResultSchema>;
-export type DemoResult = ValidationResult | RunCommandResult | CheckCommandResult | RenderCommandResult | VerificationReport | WarmCommandResult | DiffCommandResult | PruneCommandResult | ImportCommandResult | InspectResult | DoctorResult | ActivateResult | LicenceResult;
+export type PublishResult = z.infer<typeof PublishResultSchema>;
+export type DemoResult = ValidationResult | RunCommandResult | CheckCommandResult | RenderCommandResult | VerificationReport | WarmCommandResult | DiffCommandResult | CompareCommandResult | InitResult | PruneCommandResult | ImportCommandResult | InspectResult | DoctorResult | ActivateResult | LicenceResult | PublishResult;
 /**
  * Renders a filesystem location for display in a result, relative to `root` when it
  * lies inside it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaintake/scenario",
-  "version": "1.14.0",
+  "version": "1.23.0",
   "description": "Authoring SDK for PlainTake demo scenarios: defineDemo and the scenario DSL types. Install for editor autocomplete; the PlainTake binary ships a runtime fallback.",
   "license": "MIT",
   "type": "module",