pixelkiln 0.34.0 → 0.35.0

package/CONTRIBUTING.md

@@ -97,6 +97,11 @@ wire contracts.
   especially dangerous when a command can spend provider quota.
 - Never overwrite a generated file whose current bytes differ from its recorded
   hash, and never make deletion an implicit side effect of recovery/triage.
+- The CLI is a thin layer. `src/cli.ts` is the bin entry, `src/cli/main.ts`
+  maps command names to modules under `src/cli/commands/`, `src/cli/args.ts`
+  parses flags, and `src/cli/project.ts` opens a project the way every
+  command needs it. A command module should read and print; anything it
+  computes belongs in `src/pipeline/` where the library exports it.
 
 ## Pull requests
 

package/README.md

@@ -65,8 +65,8 @@ provenance and no long-lived npm token.
 
 ### Local human review
 
-`pixelkiln pick` opens a local candidate sheet — native aspect ratios, crisp
-small sprites, and no model choosing artwork for you.
+`pixelkiln pick` opens a local candidate sheet with native aspect ratios and
+crisp small sprites. No model chooses artwork for you.
 
 ![PixelKiln candidate review UI](./website/public/review-ui-showcase.jpg)
 
@@ -84,7 +84,7 @@ reviews from the page under that ceiling.
 Hand edits live beside the art, not in place of the record. [`pixelkiln edit`](docs/CLI.md#edit)
 opens a copy in your own editor; with `--edit` the gallery does the same, or opens
 it in a pinned, hash-verified [Pixelorama](docs/CLI.md#tools) build right in the page
-and saves it back — layers kept, frame and tile sets one file per member.
+and saves it back with its layers kept, one file per member for frame and tile sets.
 
 ![PixelKiln in-browser editor](./website/public/gallery-editor-showcase.jpg)
 
@@ -337,18 +337,18 @@ artifacts agree rather than regenerate them. See
 ## TypeScript library
 
 ```ts
-import {
-  buildPlan,
-  loadLock,
-  loadManifest,
-  resolveSpecs,
-} from "pixelkiln"
-const loaded = await loadManifest("pixelkiln.manifest.json")
-const specs = await resolveSpecs(loaded)
-const plan = await buildPlan(specs, await loadLock("pixelkiln.lock.json"))
+import { openProject } from "pixelkiln"
+
+const project = await openProject("pixelkiln.manifest.json")
+const plan = await project.plan()
 console.log(plan.groups, plan.actionable.length)
 ```
 
+`openProject` reads the env files beside the manifest, loads it, resolves
+every spec, and loads the lockfile with its paths canonicalised for this
+checkout. `project.specs`, `project.lock`, and `project.lockPath` are what the
+lower-level `submit`, `poll`, and `fetchAssets` calls take.
+
 The package also exports audit and image-regression gates, quality-profile
 inspection and refinement, revision-readiness checks, lock/output helpers, the
 gallery snapshot and server, hand edits and the editor install, provider contracts,

package/dist/cli.d.ts

@@ -1,104 +1 @@
 #!/usr/bin/env node
-import { z } from 'zod';
-
-declare const GridConfidenceSchema: z.ZodEnum<["low", "medium", "high"]>;
-type GridConfidence = z.infer<typeof GridConfidenceSchema>;
-
-interface ReviewReadyInfo {
-    url: string;
-    keys: string[];
-}
-
-type TilesetFormat = "generic" | "tiled" | "godot";
-
-interface CliWritable {
-    isTTY?: boolean;
-    write(chunk: string): unknown;
-}
-/**
- * Interactive readiness is progress, not command output. Keep it on stdout in
- * a terminal, but use stderr when stdout is piped so consumers such as `tail`
- * cannot hold the only copy of the live URL until the server exits.
- */
-declare function announceReviewReady(info: ReviewReadyInfo, stdout?: CliWritable, stderr?: CliWritable): void;
-/** Same stream rule as review readiness: the live URL must not wait behind a pipe. */
-declare function announceGalleryReady(url: string, count: number, stdout?: CliWritable, stderr?: CliWritable, edit?: boolean, budget?: string | null): void;
-interface Args {
-    command: string;
-    manifest: string;
-    lock: string;
-    styles: string[];
-    assets: string[];
-    force: boolean;
-    yes: boolean;
-    budget?: number;
-    /** Repeatable provider-keyed budgets used by a mixed-provider run. */
-    providerBudgets: Record<string, number>;
-    dryRun: boolean;
-    all: boolean;
-    json: boolean;
-    check: boolean;
-    noOpen: boolean;
-    tag: boolean;
-    /** gallery: allow the page to edit manifest intent (prompts, sizes, tags, new assets). */
-    edit: boolean;
-    /** gallery: do not offer the in-browser editor even with --edit. */
-    noEditor: boolean;
-    /** fetch: re-download downloaded outputs and replace files whose object changed upstream. */
-    refresh: boolean;
-    from?: string;
-    out?: string;
-    generator?: string;
-    exclude: string[];
-    name?: string;
-    writePrompts: boolean;
-    columns?: number;
-    port?: number;
-    inputs?: string;
-    claims: string[];
-    format?: TilesetFormat;
-    outputRoles: string[];
-    primaryOnly: boolean;
-    prune: boolean;
-    maxDistance?: number;
-    minTransparency?: number;
-    maxColors?: number;
-    sigma?: number;
-    palette: string[];
-    fixerPython?: string;
-    fixerRevision?: string;
-    minGridConfidence?: GridConfidence;
-    reviewer?: string;
-    note?: string;
-    /** ComfyUI `models` directory used for offline recipe model verification. */
-    modelRoot?: string;
-    /** restore: a previous generation to bring back — 1-based, newest first, or an output hash prefix. */
-    generation?: string;
-    /** Subcommand for `quality`, `recipe`, `refine`, or `workspace`. */
-    subcommand?: string;
-    /** Path to a workspace catalog. Defaults to `pixelkiln.workspace.json` in cwd. */
-    workspace?: string;
-    /** Positional target for recipe and workspace subcommands. */
-    target?: string;
-    /** Account provider selector; also the `workspace add` catalog provider hint. */
-    provider?: string;
-    /** `workspace add`: free-form account label, e.g. distinguishing sandboxes. */
-    account?: string;
-    /**
-     * Raw `--lock` value with no manifest-relative default applied. `workspace
-     * add` needs to know whether the user actually passed `--lock`, since the
-     * ambient default (beside `--manifest`, which usually names an unrelated
-     * project) is meaningless for the manifest being registered.
-     */
-    explicitLock?: string;
-}
-declare const COMMANDS: readonly ["init", "plan", "doctor", "gen", "submit", "poll", "pick", "fetch", "restore", "adopt", "accept", "salvage", "purge", "prune", "audit", "cache", "pack", "mount", "export", "tag", "balance", "status", "gallery", "edit", "tools", "history", "quality", "refine", "recipe", "workspace", "help", "--help", "-h", "--version", "-v"];
-/**
- * Strict parsing. Unknown flags are a hard error rather than being ignored,
- * because a silently-dropped filter is expensive here: `--styles neon` (plural,
- * a typo) would otherwise fall through to "no filter" and generate the entire
- * manifest instead of one style.
- */
-declare function parseArgs(argv: string[]): Args;
-
-export { COMMANDS, announceGalleryReady, announceReviewReady, parseArgs };