@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/core/cache.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal filesystem surface needed for atomic, concurrency-safe cache
+ * persistence. Matches the project install transaction contract: verified
+ * bytes are written to a writer-unique sibling staging file and `renameSync`'d
+ * over the final path, so readers never observe a truncated cache and a crash
+ * never leaves a partial cache at the final path.
+ */
+export interface CacheIo {
+    readonly mkdirSync: (path: string) => void;
+    readonly writeFileSync: (path: string, bytes: Uint8Array) => void;
+    readonly renameSync: (from: string, to: string) => void;
+    readonly existsSync: (path: string) => boolean;
+    readonly rmSync: (path: string, options?: {
+        readonly force?: boolean;
+    }) => void;
+    readonly readFileSync?: (path: string) => Uint8Array;
+    readonly readdirSync?: (path: string) => readonly string[];
+}
+/**
+ * Atomically persist verified bytes to a cache path.
+ *
+ * Concurrency contract (MC.5): every writer uses a PID + random suffixed
+ * staging file, so concurrent processes never share a staging file; the final
+ * rename is atomic on POSIX and Node uses `MOVEFILE_REPLACE_EXISTING` on
+ * Windows. When `expectedSha256` is provided and the final path already holds
+ * exactly those bytes, the write is skipped (idempotent fast path), so a second
+ * writer that lost the rename race reports success without rewriting.
+ *
+ * Staging files left behind by a crashed writer are inert (never read) and are
+ * swept on the next successful write only when their owner PID is proven
+ * dead. Live or unknown writers are preserved, including writers already
+ * staging when this call begins.
+ */
+export declare function cacheArtifact(io: CacheIo, path: string, bytes: Uint8Array, expectedSha256?: string): void;

package/dist/core/cache.js

@@ -0,0 +1,96 @@
+import { createHash, randomBytes } from "node:crypto";
+import { basename, join } from "node:path";
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Atomically persist verified bytes to a cache path.
+ *
+ * Concurrency contract (MC.5): every writer uses a PID + random suffixed
+ * staging file, so concurrent processes never share a staging file; the final
+ * rename is atomic on POSIX and Node uses `MOVEFILE_REPLACE_EXISTING` on
+ * Windows. When `expectedSha256` is provided and the final path already holds
+ * exactly those bytes, the write is skipped (idempotent fast path), so a second
+ * writer that lost the rename race reports success without rewriting.
+ *
+ * Staging files left behind by a crashed writer are inert (never read) and are
+ * swept on the next successful write only when their owner PID is proven
+ * dead. Live or unknown writers are preserved, including writers already
+ * staging when this call begins.
+ */
+export function cacheArtifact(io, path, bytes, expectedSha256) {
+    io.mkdirSync(join(path, ".."));
+    const orphans = new Set(io.readdirSync ? io.readdirSync(join(path, "..")) : []);
+    const stagingPattern = `${basename(path)}.staging-`;
+    if (expectedSha256 && io.existsSync(path) && io.readFileSync) {
+        const existing = io.readFileSync(path);
+        if (existing.byteLength === bytes.byteLength && sha256Hex(existing) === expectedSha256) {
+            return;
+        }
+    }
+    const staging = `${path}.staging-${process.pid}-${randomBytes(4).toString("hex")}`;
+    try {
+        io.writeFileSync(staging, bytes);
+        try {
+            io.renameSync(staging, path);
+        }
+        catch (error) {
+            // Cross-process race: another writer may have replaced `path` first. Only
+            // treat that as success when the surviving bytes actually match what we
+            // set out to persist; otherwise rethrow so a corrupt cache is not kept.
+            if (expectedSha256 && io.existsSync(path) && io.readFileSync) {
+                const existing = io.readFileSync(path);
+                if (existing.byteLength === bytes.byteLength && sha256Hex(existing) === expectedSha256) {
+                    try {
+                        io.rmSync(staging, { force: true });
+                    }
+                    catch {
+                        /* Best effort own staging cleanup. */
+                    }
+                    return;
+                }
+            }
+            throw error;
+        }
+        if (io.rmSync && io.readdirSync) {
+            for (const name of orphans) {
+                if (!name.startsWith(stagingPattern))
+                    continue;
+                const owner = /^(\d+)-[a-f0-9]{8}$/.exec(name.slice(stagingPattern.length));
+                if (!owner)
+                    continue;
+                const pid = Number(owner[1]);
+                if (!Number.isSafeInteger(pid) || pid < 1 || pid > 2147483647)
+                    continue;
+                let dead = false;
+                try {
+                    process.kill(pid, 0);
+                }
+                catch (error) {
+                    dead =
+                        typeof error === "object" &&
+                            error !== null &&
+                            "code" in error &&
+                            error.code === "ESRCH";
+                }
+                if (!dead)
+                    continue;
+                try {
+                    io.rmSync(join(join(path, ".."), name), { force: true });
+                }
+                catch {
+                    // Best-effort orphan sweep.
+                }
+            }
+        }
+    }
+    catch (error) {
+        try {
+            io.rmSync(staging, { force: true });
+        }
+        catch {
+            // Best-effort cleanup; the writer-unique staging file is never read.
+        }
+        throw error;
+    }
+}

package/dist/core/context.d.ts

@@ -1,6 +1,25 @@
 export interface UiChoice {
     readonly value: string;
     readonly label: string;
+    /** When true, renderer inserts a blank line before this option (e.g. Back). */
+    readonly separatorBefore?: boolean;
+}
+/** W3-A: a structured progress tick (bytes or item counts). */
+export interface ProgressBarEvent {
+    readonly done?: number;
+    readonly total?: number;
+    readonly label?: string;
+    readonly detail?: string;
+}
+export interface ProgressBarHandle {
+    readonly update: (event?: ProgressBarEvent) => void;
+    readonly stop: (message?: string) => void;
+}
+/** W3-C: strict task lifecycle for work without a progress bar. */
+export interface TaskHandle {
+    readonly succeed: (message?: string) => void;
+    readonly fail: (message?: string) => void;
+    readonly timeout: (message?: string) => void;
 }
 export interface CommandUi {
     readonly select: (message: string, choices: readonly UiChoice[], signal: AbortSignal) => Promise<string | undefined>;
@@ -11,6 +30,13 @@ export interface CommandUi {
         readonly update?: (message: string) => void;
         readonly stop: (message?: string) => void;
     };
+    /**
+     * W3-A: optional richer progress surface. Adapters that cannot render one
+     * (JSON / non-TTY) omit it; callers fall back to `progress`.
+     */
+    readonly progressBar?: (label: string, signal: AbortSignal) => ProgressBarHandle;
+    /** W3-C: optional strict task status surface. */
+    readonly task?: (label: string, signal: AbortSignal) => TaskHandle;
 }
 /** Dependencies shared by command use cases; it deliberately contains no Node globals. */
 export interface CommandContext {

package/dist/core/doctor.d.ts

@@ -0,0 +1,48 @@
+import { type DiagnoseOutcome } from "../project/anchors/diagnose.js";
+import type { DiagnosticReport, PlannedFileChange } from "../project/anchors/types.js";
+import type { IconCatalog } from "../catalog/catalog.js";
+import type { Target } from "../commands/parser.js";
+export type DoctorMode = "diagnose" | "check" | "dry-run" | "apply";
+export interface DoctorResult {
+    readonly mode: DoctorMode;
+    readonly ok: true;
+    readonly report: DiagnosticReport;
+    readonly written?: readonly string[];
+    readonly alreadyConfigured?: boolean;
+}
+/** Read-only four-anchor diagnosis. Never writes. */
+export declare function runDoctorDiagnose(cwd: string, sourceCatalog?: IconCatalog): DiagnoseOutcome;
+/** Human-readable table (manifest + config always shown). */
+export declare function formatDoctorReport(report: DiagnosticReport): string;
+/** JSON-stable machine report. Paths are POSIX-relative to projectRoot (never absolute home). */
+export declare function doctorJson(report: DiagnosticReport): Record<string, unknown>;
+/**
+ * `moeicons doctor --check`: exit non-zero when any required anchor is not OK.
+ * Required anchors are manifest/config/application; style is optional.
+ */
+export declare function checkRequiresFix(report: DiagnosticReport): boolean;
+/** Build the complete init plan (config create + application + style fixes). */
+export declare function buildInitPlan(cwd: string, target?: Target, confirmed?: {
+    adapter?: string;
+    entry?: string;
+    style?: string;
+}, sourceCatalog?: IconCatalog): {
+    readonly outcome: DiagnoseOutcome;
+};
+/** Collect safe planned fixes from a diagnose outcome (already deduped). */
+export declare function collectSafeFixes(outcome: DiagnoseOutcome): readonly PlannedFileChange[];
+/** Human-readable unified-style diffs for a planned change set. */
+export declare function formatPlannedDiffs(changes: readonly PlannedFileChange[]): string;
+/** Machine-readable diffs for `--json --dry-run`. */
+export declare function plannedDiffsJson(changes: readonly PlannedFileChange[]): readonly Record<string, unknown>[];
+export interface DoctorApplyFailure {
+    readonly ok: false;
+    readonly message: string;
+    readonly written: readonly string[];
+}
+export type DoctorApplyOutcome = DoctorResult | DoctorApplyFailure;
+/**
+ * Apply a confirmed safe plan (all anchors' fixes). Transactional; a second run
+ * is a no-op (`alreadyConfigured`).
+ */
+export declare function runDoctorApply(cwd: string, fixes: readonly PlannedFileChange[]): DoctorApplyOutcome;

package/dist/core/doctor.js

@@ -0,0 +1,190 @@
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { diagnoseProject } from "../project/anchors/diagnose.js";
+import { applyPlannedChanges } from "../project/anchors/apply.js";
+import { withProjectLockSync } from "../project/project-lock.js";
+import { loadInstalledCatalogState } from "./generate.js";
+const STATUS_LABEL = {
+    ok: "OK",
+    missing: "MISSING",
+    invalid: "INVALID",
+    ambiguous: "AMBIGUOUS",
+    unsupported: "UNSUPPORTED",
+    "not-required": "N/A",
+};
+/** Read-only four-anchor diagnosis. Never writes. */
+export function runDoctorDiagnose(cwd, sourceCatalog) {
+    return diagnoseProject({ cwd, sourceCatalog: sourceCatalog ?? diagnosticCatalog(cwd) });
+}
+/** Human-readable table (manifest + config always shown). */
+export function formatDoctorReport(report) {
+    const lines = [];
+    for (const anchor of report.anchors) {
+        const label = STATUS_LABEL[anchor.status] ?? anchor.status.toUpperCase();
+        const path = anchor.path
+            ? report.projectRoot
+                ? toPosixRelative(report.projectRoot, anchor.path)
+                : anchor.path
+            : "-";
+        const name = anchorName(anchor.kind);
+        lines.push(`${name.padEnd(22)} ${label.padEnd(10)} ${path}`);
+        for (const evidence of anchor.evidence)
+            lines.push(`  - ${evidence}`);
+        if (anchor.fixes.length) {
+            lines.push(`  fixes: ${anchor.fixes.map((f) => `${f.kind} ${f.path}`).join(", ")}`);
+        }
+    }
+    return lines.join("\n");
+}
+function anchorName(kind) {
+    switch (kind) {
+        case "manifest":
+            return "Project manifest";
+        case "config":
+            return "Moeicons config";
+        case "application":
+            return "Application integration";
+        case "style":
+            return "Styling integration";
+    }
+}
+function toPosixRelative(root, path) {
+    if (!isAbsolute(path))
+        return path.split(sep).join("/");
+    const rel = relative(root, path);
+    if (!rel || rel === "")
+        return ".";
+    return rel.split(sep).join("/");
+}
+/** JSON-stable machine report. Paths are POSIX-relative to projectRoot (never absolute home). */
+export function doctorJson(report) {
+    const root = report.projectRoot;
+    return {
+        ok: !checkRequiresFix(report),
+        ...(root ? { projectRoot: "." } : {}),
+        anchors: report.anchors.map((a) => ({
+            kind: a.kind,
+            status: a.status,
+            ...(a.path && root ? { path: toPosixRelative(root, a.path) } : a.path ? { path: a.path } : {}),
+            candidates: root
+                ? a.candidates.map((c) => toPosixRelative(root, c))
+                : [...a.candidates],
+            evidence: a.evidence,
+            fixes: a.fixes.map((f) => ({
+                kind: f.kind,
+                path: f.path,
+                ...(f.before !== undefined ? { before: f.before } : {}),
+                after: f.after,
+            })),
+        })),
+    };
+}
+/**
+ * `moeicons doctor --check`: exit non-zero when any required anchor is not OK.
+ * Required anchors are manifest/config/application; style is optional.
+ */
+export function checkRequiresFix(report) {
+    const required = [
+        "manifest",
+        "config",
+        "application",
+    ];
+    return report.anchors.some((a) => required.includes(a.kind) && a.status !== "ok" && a.status !== "not-required");
+}
+function diagnosticCatalog(cwd) {
+    const state = loadInstalledCatalogState(cwd, { readFileSync, existsSync });
+    if (state.status === "invalid")
+        throw new Error(state.message);
+    return state.status === "ok" ? state.catalog : undefined;
+}
+/** Build the complete init plan (config create + application + style fixes). */
+export function buildInitPlan(cwd, target, confirmed, sourceCatalog) {
+    const adapter = confirmed?.adapter ?? (target === "vue" ? "vite-vue" : target === "react" ? "vite-react" : target === "vanilla" ? "vanilla" : target === "assets" ? "assets-only" : undefined);
+    return { outcome: diagnoseProject({ cwd, sourceCatalog: sourceCatalog ?? diagnosticCatalog(cwd), ...(adapter ? { confirmed: { ...confirmed, adapter } } : {}) }) };
+}
+/** Collect safe planned fixes from a diagnose outcome (already deduped). */
+export function collectSafeFixes(outcome) {
+    return outcome.fixes;
+}
+/** Human-readable unified-style diffs for a planned change set. */
+export function formatPlannedDiffs(changes) {
+    if (changes.length === 0)
+        return "";
+    const blocks = [];
+    for (const change of changes) {
+        blocks.push(formatOneDiff(change));
+    }
+    return blocks.join("\n\n");
+}
+function formatOneDiff(change) {
+    const path = change.path;
+    if (change.kind === "create" || change.before === undefined) {
+        const added = change.after.split("\n").map((line) => `+${line}`).join("\n");
+        return `*** create ${path}\n--- /dev/null\n+++ b/${path}\n${added}`;
+    }
+    const beforeLines = change.before.split("\n");
+    const afterLines = change.after.split("\n");
+    const removed = beforeLines.map((line) => `-${line}`).join("\n");
+    const added = afterLines.map((line) => `+${line}`).join("\n");
+    return `*** replace ${path}\n--- a/${path}\n+++ b/${path}\n${removed}\n${added}`;
+}
+/** Machine-readable diffs for `--json --dry-run`. */
+export function plannedDiffsJson(changes) {
+    return changes.map((change) => ({
+        kind: change.kind,
+        path: change.path,
+        diff: formatOneDiff(change),
+    }));
+}
+const FS = {
+    existsSync: (path) => existsSync(path),
+    readTextFileSync: (path) => readFileSync(path, "utf8"),
+    mkdirSync: (path) => {
+        mkdirSync(path, { recursive: true });
+    },
+    writeTextFileSync: (path, content) => {
+        writeFileSync(path, content);
+    },
+    renameSync: (from, to) => renameSync(from, to),
+    rmSync: (path) => {
+        rmSync(path, { recursive: true, force: true });
+    },
+};
+function projectRootOf(cwd) {
+    let dir = cwd;
+    for (;;) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error("no project found");
+        dir = parent;
+    }
+}
+function emptyReport(projectRoot) {
+    return { projectRoot, anchors: [] };
+}
+/**
+ * Apply a confirmed safe plan (all anchors' fixes). Transactional; a second run
+ * is a no-op (`alreadyConfigured`).
+ */
+export function runDoctorApply(cwd, fixes) {
+    const root = projectRootOf(cwd);
+    let outcome;
+    try {
+        outcome = withProjectLockSync(root, "doctor", () => applyPlannedChanges(root, fixes, FS));
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : String(error), written: [] };
+    }
+    if (!outcome.ok) {
+        return { ok: false, message: outcome.message, written: [] };
+    }
+    return {
+        mode: "apply",
+        ok: true,
+        alreadyConfigured: outcome.alreadyConfigured,
+        written: outcome.written,
+        report: emptyReport(root),
+    };
+}

package/dist/core/free-download.d.ts

@@ -1,11 +1,18 @@
+import { type ResourceRefs } from "./selected-resources.js";
+import { type ConfigDocument, type MoeiconsConfigFile } from "../project/config.js";
 import { type DownloadLimits } from "../project/install.js";
-import { type ReleaseDescriptor } from "./release-descriptor.js";
+import { type CacheIo } from "./cache.js";
+import { type MetadataArchiveFiles } from "../metadata/archive.js";
+import { type ReleaseDescriptor, type ReleaseMetadataRef } from "./release-descriptor.js";
 export declare const DESCRIPTOR_MAX_BYTES: number;
 export declare const ARTIFACT_MAX_BYTES: number;
-export declare const DOWNLOAD_TIMEOUT_MS = 30000;
+export declare const METADATA_MAX_BYTES: number;
+export declare const DOWNLOAD_TIMEOUT_MS = 120000;
 export declare const MAX_REDIRECTS = 5;
 export declare const DESCRIPTOR_NAME = "release-descriptor.json";
 export declare const DESCRIPTOR_SHA_NAME = "release-descriptor.json.sha256";
+export declare const RELEASE_LATEST_NAME = "release-latest.json";
+export declare const MAX_DOWNLOAD_ATTEMPTS = 3;
 export type FreeDownloadFailure = {
     readonly ok: false;
     readonly reason: "network";
@@ -30,18 +37,36 @@ export type FreeDownloadFailure = {
     readonly ok: false;
     readonly reason: "cancelled";
     readonly message: string;
+} | {
+    readonly ok: false;
+    readonly reason: "disk-full";
+    readonly message: string;
 };
+export interface SelectedResourceDownload {
+    readonly files: Readonly<Record<string, Uint8Array>>;
+    readonly refs: ResourceRefs;
+    readonly indexBytes: Uint8Array;
+    readonly payloadBytes: number;
+    readonly networkBytes: number;
+    readonly cacheHits: number;
+    readonly fallbacks: readonly string[];
+}
 export type FreeDownloadSuccess = {
     readonly ok: true;
     readonly descriptor: ReleaseDescriptor;
     readonly descriptorSha256: string;
     readonly artifactBytes: Uint8Array;
+    readonly selected?: SelectedResourceDownload;
+    readonly downloadNote?: string;
     readonly catalogJson: string;
     readonly cacheHit: boolean;
     readonly tag: string;
+    readonly metadataSha256: string;
+    readonly manifestJson: string;
+    readonly manualMd: string;
 };
 export type FreeDownloadResult = FreeDownloadSuccess | FreeDownloadFailure;
-export interface FreeDownloadIo {
+export interface FreeDownloadIo extends CacheIo {
     readonly fetchFn: typeof fetch;
     readonly readFileSync: (path: string) => Uint8Array;
     readonly writeFileSync: (path: string, data: Uint8Array) => void;
@@ -55,12 +80,45 @@ export interface FreeDownloadIo {
     readonly cliVersion: string;
     readonly signal: AbortSignal;
     readonly onProgress?: DownloadLimits["onProgress"];
+    readonly statfs?: (dir: string) => {
+        readonly availableBytes: number;
+    } | undefined;
 }
 export declare function artifactCachePath(cacheDir: string, fullVersion: string, sha256: string): string;
+export declare function metadataCachePath(cacheDir: string, fullVersion: string, sha256: string): string;
+/** Best-effort disk-space preflight; missing statfs support is treated as "enough". */
+export declare function hasEnoughFreeSpace(io: FreeDownloadIo, dir: string, requiredBytes: number): boolean;
+export interface ExtractedMetadata extends MetadataArchiveFiles {
+    metadataSha256: string;
+}
+/**
+ * Download the small metadata archive, verify the whole-archive SHA-256 plus
+ * size and every nested file digest, then cache it atomically.
+ */
+export declare function downloadMetadataArchive(io: FreeDownloadIo, metadataRef: ReleaseMetadataRef, expectedCatalogSha: string, expectedTier: "free" | "pro", expectedVersion: string, tag: string, allowLocalTest?: boolean): Promise<{
+    ok: true;
+    value: ExtractedMetadata;
+    cacheHit: boolean;
+} | FreeDownloadFailure>;
+/**
+ * Fetch the published release index → verify descriptor. Older releases that
+ * predate release-latest.json fall back to the descriptor SHA sidecar. Does not
+ * download the code artifact; used by metadata-only sync and by the full download.
+ */
+export declare function fetchFreeDescriptor(io: FreeDownloadIo, sourceVersion: string): Promise<{
+    ok: true;
+    descriptor: ReleaseDescriptor;
+    descriptorSha256: string;
+    tag: string;
+} | FreeDownloadFailure>;
 /**
  * Fetch descriptor sidecar → verify descriptor → download free.filename from
- * the descriptor (never guessed) → verify archive + nested catalog checksums.
- * Local `fixtureDir` stands in for a GitHub Release directory.
+ * the descriptor (never guessed) → verify archive + nested catalog checksums →
+ * download/verify/cache the matching metadata archive.
  */
-export declare function downloadFreeRelease(io: FreeDownloadIo, sourceVersion: string): Promise<FreeDownloadResult>;
+export declare function downloadFreeRelease(io: FreeDownloadIo, sourceVersion: string, selection?: {
+    readonly config: MoeiconsConfigFile;
+    readonly document: ConfigDocument;
+    readonly onPlan?: (message: string) => void;
+}): Promise<FreeDownloadResult>;
 export declare function bundledSourceVersion(): string;