@michinarai/cli 0.0.0-stage → 0.1.1

package/dist/generated/api.js

@@ -0,0 +1,6 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};
+//# sourceMappingURL=api.js.map

package/dist/generated/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/generated/api.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/lib/credentials.d.ts

@@ -0,0 +1,8 @@
+export declare const keychainService: (naraiUrl: string) => string;
+export interface CredentialStore {
+    get(naraiUrl: string): Promise<string | null>;
+    set(naraiUrl: string, token: string): Promise<void>;
+    /** Whether there was one to delete. */
+    delete(naraiUrl: string): Promise<boolean>;
+}
+export declare const keychain: CredentialStore;

package/dist/lib/credentials.js

@@ -0,0 +1,45 @@
+import { NaraiError } from "./errors.js";
+/** The one place a person's Narai session lives: the OS keychain (macOS Keychain, Windows Credential Manager, the
+ *  Secret Service on Linux), one entry per Narai host, holding the refresh token. No file fallback: a machine without
+ *  a keychain (CI) uses a token in NARAI_TOKEN. */
+const ACCOUNT = "refresh_token";
+export const keychainService = (naraiUrl) => `ai.michinar.narai-cli.${new URL(naraiUrl).host}`;
+class KeychainUnavailableError extends NaraiError {
+    constructor(cause) {
+        super(`the OS keychain isn't available (${cause instanceof Error ? cause.message : String(cause)}); on a machine without one, set NARAI_TOKEN`, "keychain_unavailable");
+    }
+}
+/** Loaded on first use: CI runs with NARAI_TOKEN and never loads the native module. */
+async function entry(naraiUrl) {
+    let keyring;
+    try {
+        keyring = await import("@napi-rs/keyring");
+    }
+    catch (error) {
+        throw new KeychainUnavailableError(error);
+    }
+    return new keyring.AsyncEntry(keychainService(naraiUrl), ACCOUNT);
+}
+async function guarded(action) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        throw new KeychainUnavailableError(error);
+    }
+}
+export const keychain = {
+    async get(naraiUrl) {
+        const e = await entry(naraiUrl);
+        return (await guarded(() => e.getPassword())) ?? null;
+    },
+    async set(naraiUrl, token) {
+        const e = await entry(naraiUrl);
+        await guarded(() => e.setPassword(token));
+    },
+    async delete(naraiUrl) {
+        const e = await entry(naraiUrl);
+        return guarded(() => e.deleteCredential());
+    },
+};
+//# sourceMappingURL=credentials.js.map

package/dist/lib/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/lib/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;mDAEmD;AACnD,MAAM,OAAO,GAAG,eAAe,CAAC;AAEhC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,yBAAyB,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;AAS/G,MAAM,wBAAyB,SAAQ,UAAU;IAC/C,YAAY,KAAc;QACxB,KAAK,CACH,oCAAoC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,EACxI,sBAAsB,CACvB,CAAC;IACJ,CAAC;CACF;AAED,uFAAuF;AACvF,KAAK,UAAU,KAAK,CAAC,QAAgB;IACnC,IAAI,OAA0C,CAAC;IAC/C,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;AACpE,CAAC;AAED,KAAK,UAAU,OAAO,CAAI,MAAwB;IAChD,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,EAAE,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAoB;IACvC,KAAK,CAAC,GAAG,CAAC,QAAQ;QAChB,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChC,OAAO,CAAC,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC;IACxD,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK;QACvB,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,QAAQ;QACnB,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChC,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC7C,CAAC;CACF,CAAC"}

package/dist/lib/deps.d.ts

@@ -0,0 +1,12 @@
+import { type CredentialStore } from "./credentials.js";
+/** What touches the person's machine beyond files: swapped in tests. */
+export declare const deps: {
+    credentials: CredentialStore;
+    stdinIsTTY: () => boolean;
+    stdoutIsTTY: () => boolean;
+    confirm: (message: string) => Promise<boolean>;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    /** Opens the sign-in page in the person's browser; the address is printed too, so a failure here is no matter. */
+    openBrowser: (url: string) => void;
+};

package/dist/lib/deps.js

@@ -0,0 +1,23 @@
+import { spawn } from "node:child_process";
+import confirm from "@inquirer/confirm";
+import { keychain } from "./credentials.js";
+/** What touches the person's machine beyond files: swapped in tests. */
+export const deps = {
+    credentials: keychain,
+    stdinIsTTY: () => Boolean(process.stdin.isTTY),
+    stdoutIsTTY: () => Boolean(process.stdout.isTTY),
+    confirm: (message) => confirm({ message, default: false }),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+    /** Opens the sign-in page in the person's browser; the address is printed too, so a failure here is no matter. */
+    openBrowser: (url) => {
+        const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+        try {
+            spawn(command, args, { stdio: "ignore", detached: true }).on("error", () => undefined).unref();
+        }
+        catch {
+            // printed already
+        }
+    },
+};
+//# sourceMappingURL=deps.js.map

package/dist/lib/deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deps.js","sourceRoot":"","sources":["../../src/lib/deps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,OAAO,MAAM,mBAAmB,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAwB,MAAM,kBAAkB,CAAC;AAElE,wEAAwE;AACxE,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,WAAW,EAAE,QAA2B;IACxC,UAAU,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;IAC9C,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;IAChD,OAAO,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAClE,KAAK,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC9E,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IACrB,kHAAkH;IAClH,WAAW,EAAE,CAAC,GAAW,EAAQ,EAAE;QACjC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACjK,IAAI,CAAC;YACH,KAAK,CAAC,OAAO,EAAE,IAAgB,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,CAAC;QAC7G,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/lib/digest.d.ts

@@ -0,0 +1,10 @@
+export interface FileDigest {
+    path: string;
+    sha256: string;
+    size: number;
+}
+/** Every file of a release, with its sha256 and size, sorted by path. The manifest itself isn't one of them. */
+export declare function digestFiles(dir: string): Promise<FileDigest[]>;
+/** sha256 over the file list's canonical JSON (RFC 8785; for these strings and integers: keys sorted, no space), as
+ *  Narai's registry computes it. */
+export declare function bundleDigest(files: readonly FileDigest[]): string;

package/dist/lib/digest.js

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { MANIFEST } from "./project.js";
+/** Paths compared by code point, as Narai's registry sorts them (Python's), not by UTF-16 unit. */
+const byCodePoint = (a, b) => {
+    const points = (s) => Array.from(s, (c) => c.codePointAt(0) ?? 0);
+    const [x, y] = [points(a), points(b)];
+    for (let i = 0; i < Math.min(x.length, y.length); i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return x.length - y.length;
+};
+/** Every file of a release, with its sha256 and size, sorted by path. The manifest itself isn't one of them. */
+export async function digestFiles(dir) {
+    const files = [];
+    for (const entry of await readdir(dir, { recursive: true, withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        const full = join(entry.parentPath, entry.name);
+        const path = relative(dir, full).split(sep).join("/");
+        if (path === MANIFEST)
+            continue;
+        const bytes = await readFile(full);
+        files.push({ path, sha256: createHash("sha256").update(bytes).digest("hex"), size: bytes.length });
+    }
+    return files.sort((a, b) => byCodePoint(a.path, b.path));
+}
+/** sha256 over the file list's canonical JSON (RFC 8785; for these strings and integers: keys sorted, no space), as
+ *  Narai's registry computes it. */
+export function bundleDigest(files) {
+    const canonical = JSON.stringify(files.map(({ path, sha256, size }) => ({ path, sha256, size })));
+    return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+//# sourceMappingURL=digest.js.map

package/dist/lib/digest.js.map

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

package/dist/lib/errors.d.ts

@@ -0,0 +1,26 @@
+/** The exit codes every command answers with: a contract scripts, CI and agents branch on. */
+export declare const ExitCode: {
+    readonly ok: 0;
+    readonly error: 1;
+    /** A flag or argument the command doesn't take. */
+    readonly usage: 2;
+    /** Not signed in, or the session or token was refused. */
+    readonly auth: 3;
+    /** Only with `--detailed-exitcode`: the plan has changes (0 then means none). */
+    readonly changes: 2;
+};
+/** Every failure the CLI reports on purpose. `code` is stable and machine-readable (`--json`); `message` is for
+ *  people and never carries a secret. */
+export declare class NaraiError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly details: Record<string, unknown>;
+    constructor(message: string, code: string, exitCode?: number, details?: Record<string, unknown>);
+}
+export declare class AuthError extends NaraiError {
+    constructor(message: string, code?: string);
+}
+/** A confirmation was needed, and `--no-input` (or no terminal) ruled out asking. */
+export declare class NeedsInputError extends NaraiError {
+    constructor(message: string, details?: Record<string, unknown>);
+}

package/dist/lib/errors.js

@@ -0,0 +1,39 @@
+/** The exit codes every command answers with: a contract scripts, CI and agents branch on. */
+export const ExitCode = {
+    ok: 0,
+    error: 1,
+    /** A flag or argument the command doesn't take. */
+    usage: 2,
+    /** Not signed in, or the session or token was refused. */
+    auth: 3,
+    /** Only with `--detailed-exitcode`: the plan has changes (0 then means none). */
+    changes: 2,
+};
+/** Every failure the CLI reports on purpose. `code` is stable and machine-readable (`--json`); `message` is for
+ *  people and never carries a secret. */
+export class NaraiError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(message, code, exitCode = ExitCode.error, details = {}) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+        this.name = "NaraiError";
+    }
+}
+export class AuthError extends NaraiError {
+    constructor(message, code = "not_signed_in") {
+        super(message, code, ExitCode.auth);
+        this.name = "AuthError";
+    }
+}
+/** A confirmation was needed, and `--no-input` (or no terminal) ruled out asking. */
+export class NeedsInputError extends NaraiError {
+    constructor(message, details = {}) {
+        super(message, "needs_input", ExitCode.error, details);
+        this.name = "NeedsInputError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,EAAE,EAAE,CAAC;IACL,KAAK,EAAE,CAAC;IACR,mDAAmD;IACnD,KAAK,EAAE,CAAC;IACR,0DAA0D;IAC1D,IAAI,EAAE,CAAC;IACP,iFAAiF;IACjF,OAAO,EAAE,CAAC;CACF,CAAC;AAEX;yCACyC;AACzC,MAAM,OAAO,UAAW,SAAQ,KAAK;IAGxB;IACA;IACA;IAJX,YACE,OAAe,EACN,IAAY,EACZ,WAAmB,QAAQ,CAAC,KAAK,EACjC,UAAmC,EAAE;QAE9C,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,SAAI,GAAJ,IAAI,CAAQ;QACZ,aAAQ,GAAR,QAAQ,CAAyB;QACjC,YAAO,GAAP,OAAO,CAA8B;QAG9C,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,SAAU,SAAQ,UAAU;IACvC,YAAY,OAAe,EAAE,IAAI,GAAG,eAAe;QACjD,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,OAAO,eAAgB,SAAQ,UAAU;IAC7C,YAAY,OAAe,EAAE,UAAmC,EAAE;QAChE,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/dist/lib/http.d.ts

@@ -0,0 +1,2 @@
+/** Every request the CLI makes: no redirects followed (a token never goes where it wasn't sent), a timeout. */
+export declare function send(url: string, init?: RequestInit): Promise<Response>;

package/dist/lib/http.js

@@ -0,0 +1,11 @@
+import { NaraiError } from "./errors.js";
+/** Every request the CLI makes: no redirects followed (a token never goes where it wasn't sent), a timeout. */
+export async function send(url, init = {}) {
+    try {
+        return await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(30_000), ...init });
+    }
+    catch (error) {
+        throw new NaraiError(`couldn't reach ${new URL(url).host}: ${error.message}`, "network");
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/lib/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/lib/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,+GAA+G;AAC/G,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,GAAW,EAAE,OAAoB,EAAE;IAC5D,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IAChG,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAAC,kBAAkB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,KAAM,KAAe,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACtG,CAAC;AACH,CAAC"}

package/dist/lib/lock.d.ts

@@ -0,0 +1,4 @@
+/** Runs `action` holding the lock file at `path`, shared by every `narai` on this machine (two refreshing one
+ *  rotating token at once would leave one of them holding a dead one). The file names its owner's pid; a lock whose
+ *  owner is gone is taken over. */
+export declare function withFileLock<T>(path: string, action: () => Promise<T>): Promise<T>;

package/dist/lib/lock.js

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { deps } from "./deps.js";
+const POLL_MS = 100;
+function running(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Runs `action` holding the lock file at `path`, shared by every `narai` on this machine (two refreshing one
+ *  rotating token at once would leave one of them holding a dead one). The file names its owner's pid; a lock whose
+ *  owner is gone is taken over. */
+export async function withFileLock(path, action) {
+    await mkdir(dirname(path), { recursive: true });
+    // written whole, then linked into place: link fails when the lock exists, and no one sees a lock without its owner
+    const mine = `${path}.${process.pid}.${randomUUID()}`;
+    await writeFile(mine, String(process.pid));
+    try {
+        for (;;) {
+            try {
+                await link(mine, path);
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+            let owner;
+            try {
+                owner = Number(await readFile(path, "utf8"));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+            if (Number.isInteger(owner) && owner > 0 && running(owner))
+                await deps.sleep(POLL_MS);
+            else
+                await rm(path, { force: true });
+        }
+    }
+    finally {
+        await rm(mine, { force: true });
+    }
+    try {
+        return await action();
+    }
+    finally {
+        await rm(path, { force: true });
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/lib/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/lib/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,OAAO,GAAG,GAAG,CAAC;AAEpB,SAAS,OAAO,CAAC,GAAW;IAC1B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAQ,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;mCAEmC;AACnC,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,IAAY,EAAE,MAAwB;IAC1E,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,mHAAmH;IACnH,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,EAAE,CAAC;IACtD,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,CAAC;QACH,SAAS,CAAC;YACR,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBACvB,MAAM;YACR,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;oBAAE,MAAM,KAAK,CAAC;YACtE,CAAC;YACD,IAAI,KAAa,CAAC;YAClB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;YAC/C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;oBAAE,SAAS;gBACjE,MAAM,KAAK,CAAC;YACd,CAAC;YACD,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;;gBACjF,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,EAAE,CAAC;IACxB,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;AACH,CAAC"}

package/dist/lib/output.d.ts

@@ -0,0 +1,21 @@
+export declare const clean: (text: string) => string;
+export interface OutputOptions {
+    json: boolean;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+}
+/** Where everything a command says goes: stdout carries only the result (text, or one JSON document with `--json`);
+ *  progress, prompts and errors go to stderr. */
+export declare class Output {
+    readonly json: boolean;
+    private readonly stdout;
+    private readonly stderr;
+    constructor(options: OutputOptions);
+    /** The command's answer: `data` as JSON with `--json`, else the lines `render` gives. */
+    result(data: unknown, render: () => string | readonly string[]): void;
+    /** For people; silent with `--json`. */
+    progress(message: string): void;
+    /** What a person must see to act (where to sign in, what they confirm): written even with `--json`. */
+    prompt(message: string): void;
+    error(code: string, message: string, details?: Record<string, unknown>): void;
+}

package/dist/lib/output.js

@@ -0,0 +1,44 @@
+// What a server or a file says is printed only after control characters are taken out, so nothing a server returns
+// can move the cursor, rewrite a line or set a terminal's title.
+// eslint-disable-next-line no-control-regex -- the control characters are what's removed
+const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+export const clean = (text) => text.replace(CONTROL, "");
+/** Where everything a command says goes: stdout carries only the result (text, or one JSON document with `--json`);
+ *  progress, prompts and errors go to stderr. */
+export class Output {
+    json;
+    stdout;
+    stderr;
+    constructor(options) {
+        this.json = options.json;
+        this.stdout = options.stdout ?? process.stdout;
+        this.stderr = options.stderr ?? process.stderr;
+    }
+    /** The command's answer: `data` as JSON with `--json`, else the lines `render` gives. */
+    result(data, render) {
+        if (this.json) {
+            this.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+            return;
+        }
+        const text = render();
+        const lines = typeof text === "string" ? [text] : text;
+        if (lines.length > 0)
+            this.stdout.write(`${lines.map(clean).join("\n")}\n`);
+    }
+    /** For people; silent with `--json`. */
+    progress(message) {
+        if (!this.json)
+            this.stderr.write(`${clean(message)}\n`);
+    }
+    /** What a person must see to act (where to sign in, what they confirm): written even with `--json`. */
+    prompt(message) {
+        this.stderr.write(`${clean(message)}\n`);
+    }
+    error(code, message, details = {}) {
+        if (this.json)
+            this.stderr.write(`${JSON.stringify({ error: { code, message, ...details } })}\n`);
+        else
+            this.stderr.write(`error: ${clean(message)}\n`);
+    }
+}
+//# sourceMappingURL=output.js.map

package/dist/lib/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/lib/output.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,iEAAiE;AACjE,yFAAyF;AACzF,MAAM,OAAO,GAAG,4CAA4C,CAAC;AAE7D,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAQzE;iDACiD;AACjD,MAAM,OAAO,MAAM;IACR,IAAI,CAAU;IACN,MAAM,CAAwB;IAC9B,MAAM,CAAwB;IAE/C,YAAY,OAAsB;QAChC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;QAC/C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IACjD,CAAC;IAED,yFAAyF;IACzF,MAAM,CAAC,IAAa,EAAE,MAAwC;QAC5D,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACxD,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACvD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9E,CAAC;IAED,wCAAwC;IACxC,QAAQ,CAAC,OAAe;QACtB,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;IAED,uGAAuG;IACvG,MAAM,CAAC,OAAe;QACpB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,IAAY,EAAE,OAAe,EAAE,UAAmC,EAAE;QACxE,IAAI,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;;YAC7F,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;CACF"}

package/dist/lib/plan.d.ts

@@ -0,0 +1,13 @@
+/** One change a command would make at Narai. */
+export interface Change {
+    action: "create" | "update" | "upload";
+    target: string;
+    detail: string;
+}
+export declare const planFlags: {
+    plan: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    "detailed-exitcode": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+export declare const describeChange: (c: Change) => string;
+/** The exit a `--plan` ends with: `changes` (2) with --detailed-exitcode when there's something to do. */
+export declare const planExit: (changes: readonly Change[], detailed: boolean) => number;

package/dist/lib/plan.js

@@ -0,0 +1,10 @@
+import { Flags } from "@oclif/core";
+import { ExitCode } from "./errors.js";
+export const planFlags = {
+    plan: Flags.boolean({ description: "Only show what would change; change nothing." }),
+    "detailed-exitcode": Flags.boolean({ description: "With --plan: exit 2 when there are changes, 0 when there are none (1 is an error)." }),
+};
+export const describeChange = (c) => `  ${c.action === "create" ? "+" : c.action === "upload" ? "↑" : "~"} ${c.target}  ${c.detail}`;
+/** The exit a `--plan` ends with: `changes` (2) with --detailed-exitcode when there's something to do. */
+export const planExit = (changes, detailed) => detailed && changes.length > 0 ? ExitCode.changes : ExitCode.ok;
+//# sourceMappingURL=plan.js.map

package/dist/lib/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/lib/plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAKvC,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,8CAA8C,EAAE,CAAC;IACpF,mBAAmB,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,oFAAoF,EAAE,CAAC;CAC1I,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;AAErJ,0GAA0G;AAC1G,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAA0B,EAAE,QAAiB,EAAU,EAAE,CAChF,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC"}

package/dist/lib/project.d.ts

@@ -0,0 +1,8 @@
+import { type ToolManifest } from "@michinarai/sdk";
+/** A tool's manifest, at the root of its repository. */
+export declare const MANIFEST = "narai.tool.json";
+/** The tool's root: the nearest directory, from `from` up, that holds a manifest. */
+export declare function toolRoot(from: string): Promise<string>;
+export declare function readManifest(root: string): Promise<unknown>;
+/** The manifest, or every reason it isn't one (the SDK's checks: the schema and the registry's rules). */
+export declare function checkedManifest(root: string): Promise<ToolManifest>;

package/dist/lib/project.js

@@ -0,0 +1,37 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { manifestProblems } from "@michinarai/sdk";
+import { NaraiError } from "./errors.js";
+/** A tool's manifest, at the root of its repository. */
+export const MANIFEST = "narai.tool.json";
+/** The tool's root: the nearest directory, from `from` up, that holds a manifest. */
+export async function toolRoot(from) {
+    for (let dir = resolve(from);; dir = dirname(dir)) {
+        try {
+            await readFile(join(dir, MANIFEST));
+            return dir;
+        }
+        catch {
+            if (dirname(dir) === dir)
+                throw new NaraiError(`no ${MANIFEST} here or above: run narai init, or cd into a tool`, "no_tool");
+        }
+    }
+}
+export async function readManifest(root) {
+    const text = await readFile(join(root, MANIFEST), "utf8");
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new NaraiError(`${MANIFEST} isn't JSON: ${error.message}`, "manifest_invalid");
+    }
+}
+/** The manifest, or every reason it isn't one (the SDK's checks: the schema and the registry's rules). */
+export async function checkedManifest(root) {
+    const value = await readManifest(root);
+    const problems = manifestProblems(value);
+    if (problems.length)
+        throw new NaraiError(`${MANIFEST} doesn't match the contract`, "manifest_invalid", 1, { problems });
+    return value;
+}
+//# sourceMappingURL=project.js.map

package/dist/lib/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/lib/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAqB,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,wDAAwD;AACxD,MAAM,CAAC,MAAM,QAAQ,GAAG,iBAAiB,CAAC;AAE1C,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,KAAK,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;YACpC,OAAO,GAAG,CAAC;QACb,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG;gBAAE,MAAM,IAAI,UAAU,CAAC,MAAM,QAAQ,mDAAmD,EAAE,SAAS,CAAC,CAAC;QAC/H,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1D,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAAC,GAAG,QAAQ,gBAAiB,KAAe,CAAC,OAAO,EAAE,EAAE,kBAAkB,CAAC,CAAC;IAClG,CAAC;AACH,CAAC;AAED,0GAA0G;AAC1G,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY;IAChD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,QAAQ,CAAC,MAAM;QAAE,MAAM,IAAI,UAAU,CAAC,GAAG,QAAQ,6BAA6B,EAAE,kBAAkB,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IACzH,OAAO,KAAqB,CAAC;AAC/B,CAAC"}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@michinarai/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The narai command: scaffold, validate, build, run and register tools for Narai lessons.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Monster-Orange/mo-narai-cli.git"
+  },
+  "homepage": "https://github.com/Monster-Orange/mo-narai-cli#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "narai": "bin/run.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "oclif": {
+    "bin": "narai",
+    "dirname": "narai",
+    "commands": {
+      "strategy": "explicit",
+      "target": "./dist/commands.js",
+      "identifier": "COMMANDS"
+    },
+    "topicSeparator": " "
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --max-warnings=0",
+    "test": "vitest run",
+    "generate": "openapi-typescript node_modules/@michinarai/sdk/schema/openapi.tools.json --output src/generated/api.ts"
+  },
+  "dependencies": {
+    "@inquirer/confirm": "6.3.3",
+    "@michinarai/sdk": "0.2.1",
+    "@napi-rs/keyring": "2.1.1",
+    "@oclif/core": "5.1.7",
+    "openapi-fetch": "0.17.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.5",
+    "@types/node": "22.20.5",
+    "eslint": "9.39.5",
+    "globals": "14.0.0",
+    "openapi-typescript": "7.13.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.72.1",
+    "vitest": "3.2.7"
+  }
+}

package/templates/tool/.claude/skills/narai-tool/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: narai-tool
+description: Build, test and ship this Narai tool. Use when changing what the tool shows, what it reports (answers, practice), the commands it takes, or its manifest; and before pushing a version.
+---
+
+# Working on a Narai tool
+
+1. Change the manifest first (`narai.tool.json`): declare every payload under `payloads` with a JSON Schema, map each
+   task kind under `answers`, each activity under `practice`, each command under `commands`. Run `narai validate`.
+2. Change the tool (`src/`). Send only through the SDK session: `tool.answer(payload)` for the task Narai started,
+   `tool.practice(activity, { duration_s, attempts, payload })` outside a task, `tool.onCommand(name, fn)` for what the
+   Tutor may ask. Never a verdict field.
+3. Run it: `npm run dev`, open the host address. The harness shows every message and refuses what the manifest doesn't
+   declare, with the reason. Send the manifest's commands from its panel. `--task task.json` starts it on a task.
+4. Seal and ship: `npm run build` (writes `dist/narai.tool.json` with every file's sha256), then
+   `narai tools push --plan` to see what would change, and `narai tools push` to upload the draft.

package/templates/tool/AGENTS.md

@@ -0,0 +1,30 @@
+# Building {{name}}, a Narai tool
+
+A Narai tool is a small web app that Narai mounts in a lesson, in a sandboxed frame on its own origin. It shows the
+learner an instrument and reports what the learner did. Narai keeps the answer keys, runs every judge and owns the
+learner: a tool never grades and never learns who the learner is.
+
+## The rules
+
+- `narai.tool.json` is the tool's only source of permissions. A command, an answer, a practice activity or a payload
+  the manifest doesn't declare never crosses: the SDK refuses to send it and Narai refuses to take it.
+- Every payload is `{ "schema": "<family>.<name>@<N>", ...body }`, and its body matches the JSON Schema declared under
+  `payloads`.
+- No verdict, ever: no `correct`, `score`, `passed`, `verdict`, `grade` (the list is the SDK's `VERDICT_KEYS`) in an
+  answer's schema or body. Report what the learner did; Narai decides what it means.
+- With `assist: honors`, a task whose `assist` is `none` gets no hints and no self-checks from the tool.
+- Show the task's `prompt` as Narai sends it; it is already in the learner's language. Say `ready` in the locale the
+  tool actually renders.
+- Only the SDK talks to Narai (`connect`, `ready`, `answer`, `practice`, `onCommand`, `close`). No other `postMessage`,
+  no network unless `capabilities.network` says so.
+
+## The loop
+
+```sh
+npm install
+npm run dev        # build, then the local harness: open the host address it prints
+npm run validate   # the manifest against the contract
+npm run build      # dist/, sealed: every file's sha256 and the bundle digest
+```
+
+`narai tools push` uploads a sealed build as a draft version. See the skill in `.claude/skills/narai-tool/`.

package/templates/tool/narai.tool.json

@@ -0,0 +1,25 @@
+{
+  "id": "{{id}}",
+  "version": "0.1.0",
+  "sdk": "^1",
+  "publisher": { "name": "{{publisher}}", "url": "https://example.com" },
+  "surfaces": { "embed": { "url": "https://example.com/{{name}}/", "sdk": "^1" } },
+  "payloads": {
+    "{{family}}.answer@1": {
+      "type": "object",
+      "properties": { "text": { "type": "string", "maxLength": 200 } },
+      "required": ["text"],
+      "additionalProperties": false
+    },
+    "{{family}}.drill@1": {
+      "type": "object",
+      "properties": { "rounds": { "type": "integer", "minimum": 0 } },
+      "required": ["rounds"]
+    }
+  },
+  "answers": { "{{family}}.say": "{{family}}.answer@1" },
+  "practice": { "drill": "{{family}}.drill@1" },
+  "assist": "honors",
+  "locales": ["en", "ja"],
+  "capabilities": { "audio_out": false, "microphone": false, "network": "none" }
+}