@moewolf/moe-icons-cli 0.0.1 → 0.0.3

package/dist/project/install-metadata.d.ts

@@ -1,5 +1,11 @@
+import { type BitmapShard } from "../core/bitmap-shards.js";
 export interface InstallMetadata {
     readonly schemaVersion: 1;
+    readonly delivery?: {
+        readonly mode: "icons";
+        readonly indexSha256: string;
+        readonly bundleSha256: string;
+    };
     readonly artifactVersion: string;
     readonly tier: "free" | "pro";
     readonly target: "react" | "vue" | "vanilla" | "assets";
@@ -8,10 +14,25 @@ export interface InstallMetadata {
     readonly catalogSha256: string;
     readonly installedAt: string;
     readonly managedFiles: Readonly<Record<string, string>>;
+    /** Last successfully generated project proxy root; used for safe migrations. */
+    readonly generatedOutputDir?: string;
     /** Verified target subtree hash/size recorded at install time. */
     readonly targetSha256?: string;
     readonly targetFileCount?: number;
     readonly targetByteCount?: number;
+    /**
+     * DEV-G07: the exact bitmap shard identities selected by the config at
+     * install time. generate/repair/offline re-verify these pins before reuse.
+     */
+    readonly bitmapShards?: readonly BitmapShard[];
+    readonly bitmapShardSetSha256?: string;
+    /** A-1b: present only for an installed local-test candidate. */
+    readonly channel?: "local-test";
+    readonly publishable?: boolean;
+}
+export interface InstallMetadataParseOptions {
+    /** A-1b: accept a declared `X.Y.Z-test` local-test candidate (local context only). */
+    readonly allowLocalTest?: boolean;
 }
 export type InstalledResourceState = {
     readonly kind: "ok";
@@ -24,6 +45,6 @@ export type InstalledResourceState = {
     readonly message: string;
 };
 export declare function sha256Bytes(value: string | Uint8Array): string;
-export declare function parseInstallMetadata(raw: string): InstallMetadata | undefined;
+export declare function parseInstallMetadata(raw: string, opts?: InstallMetadataParseOptions): InstallMetadata | undefined;
 export declare function serializeInstallMetadata(metadata: InstallMetadata): string;
-export declare function readInstalledResourceState(projectRoot: string, expectedTier?: "free" | "pro"): InstalledResourceState;
+export declare function readInstalledResourceState(projectRoot: string, expectedTier?: "free" | "pro", opts?: InstallMetadataParseOptions): InstalledResourceState;

package/dist/project/install-metadata.js

@@ -1,8 +1,10 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { bitmapShardSetSha256, parseBitmapShard } from "../core/bitmap-shards.js";
 const SHA256 = /^[a-f0-9]{64}$/;
 const VERSION = /^\d+\.\d+\.\d+(?:-(?:alpha|beta))?$/;
+const LOCAL_TEST_VERSION = /^\d+\.\d+\.\d+-test$/;
 const UTC_RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
 export function sha256Bytes(value) {
     return createHash("sha256").update(value).digest("hex");
@@ -12,11 +14,13 @@ function safeManagedPath(path) {
         !path.startsWith("/") &&
         !/^[A-Za-z]:/.test(path) &&
         !path.includes("\\") &&
-        !path.split("/").includes(".."));
+        path.split("/").every((part) => part.length > 0 && part !== "." && part !== "..") &&
+        ![".git", "node_modules"].includes(path.split("/")[0] ?? ""));
 }
-export function parseInstallMetadata(raw) {
+export function parseInstallMetadata(raw, opts = {}) {
     try {
         const value = JSON.parse(raw);
+        const allowLocalTest = opts.allowLocalTest === true;
         const allowed = new Set([
             "schemaVersion",
             "artifactVersion",
@@ -27,13 +31,27 @@ export function parseInstallMetadata(raw) {
             "catalogSha256",
             "installedAt",
             "managedFiles",
+            "generatedOutputDir",
             "targetSha256",
             "targetFileCount",
             "targetByteCount",
+            "bitmapShards",
+            "bitmapShardSetSha256",
+            "delivery",
+            ...(allowLocalTest ? ["channel", "publishable"] : []),
         ]);
         if (Object.keys(value).some((key) => !allowed.has(key)) || value.schemaVersion !== 1)
             return undefined;
-        if (typeof value.artifactVersion !== "string" || !VERSION.test(value.artifactVersion))
+        const localTestMarked = value.channel === "local-test" && value.publishable === false;
+        const strictVersion = typeof value.artifactVersion === "string" && VERSION.test(value.artifactVersion);
+        // A formal (stable/alpha/beta) version must never carry the local-test marker.
+        if (strictVersion && (value.channel !== undefined || value.publishable !== undefined))
+            return undefined;
+        const versionAllowed = strictVersion ||
+            (allowLocalTest &&
+                localTestMarked &&
+                LOCAL_TEST_VERSION.test(value.artifactVersion));
+        if (!versionAllowed)
             return undefined;
         if (value.tier !== "free" && value.tier !== "pro")
             return undefined;
@@ -63,9 +81,42 @@ export function parseInstallMetadata(raw) {
             Array.isArray(value.managedFiles))
             return undefined;
         const managedFiles = value.managedFiles;
+        if (value.generatedOutputDir !== undefined &&
+            (typeof value.generatedOutputDir !== "string" ||
+                !safeManagedPath(value.generatedOutputDir) ||
+                value.generatedOutputDir.split("/").some((part) => !part || part === "." || part === "..")))
+            return undefined;
         if (Object.keys(managedFiles).length === 0 ||
             Object.entries(managedFiles).some(([path, hash]) => !safeManagedPath(path) || typeof hash !== "string" || !SHA256.test(hash)))
             return undefined;
+        if (value.delivery !== undefined) {
+            const delivery = value.delivery;
+            if (!delivery ||
+                typeof delivery !== "object" ||
+                Array.isArray(delivery) ||
+                Object.keys(delivery).some((k) => !["mode", "indexSha256", "bundleSha256"].includes(k)) ||
+                delivery.mode !== "icons" ||
+                typeof delivery.indexSha256 !== "string" ||
+                !SHA256.test(delivery.indexSha256) ||
+                typeof delivery.bundleSha256 !== "string" ||
+                !SHA256.test(delivery.bundleSha256) ||
+                managedFiles[".moeicons/resource-index.json.gz"] !== delivery.indexSha256)
+                return undefined;
+        }
+        if (value.bitmapShards !== undefined || value.bitmapShardSetSha256 !== undefined) {
+            if (!Array.isArray(value.bitmapShards) || value.bitmapShards.length === 0)
+                return undefined;
+            const shards = value.bitmapShards.map((entry) => parseBitmapShard(entry));
+            for (const shard of shards) {
+                if (shard.resourceVersion !== value.artifactVersion)
+                    return undefined;
+            }
+            const digest = value.bitmapShardSetSha256;
+            if (typeof digest !== "string" || !SHA256.test(digest))
+                return undefined;
+            if (bitmapShardSetSha256(shards) !== digest)
+                return undefined;
+        }
         return value;
     }
     catch {
@@ -75,18 +126,18 @@ export function parseInstallMetadata(raw) {
 export function serializeInstallMetadata(metadata) {
     return `${JSON.stringify(metadata, null, 2)}\n`;
 }
-export function readInstalledResourceState(projectRoot, expectedTier) {
+export function readInstalledResourceState(projectRoot, expectedTier, opts = {}) {
     const metadataPath = join(projectRoot, ".moeicons", "install-metadata.json");
     if (!existsSync(metadataPath))
         return {
             kind: "missing",
-            message: "managed install metadata is missing; run repair or reinstall",
+            message: "managed install metadata is missing; run 'moeicons install' to repair or reinstall",
         };
-    const metadata = parseInstallMetadata(readFileSync(metadataPath, "utf8"));
+    const metadata = parseInstallMetadata(readFileSync(metadataPath, "utf8"), opts);
     if (!metadata)
         return {
             kind: "invalid",
-            message: "managed install metadata is invalid; run repair or reinstall",
+            message: "managed install metadata is invalid; run 'moeicons install' to repair or reinstall",
         };
     if (expectedTier && metadata.tier !== expectedTier)
         return {

package/dist/project/install.d.ts

@@ -13,6 +13,7 @@ export interface InstallPlanItem {
     readonly bytes?: Uint8Array;
 }
 export interface InstallPlan {
+    readonly root?: string;
     readonly items: readonly InstallPlanItem[];
 }
 export interface TransactionalFs {
@@ -27,11 +28,24 @@ export interface TransactionalFsWithCopy extends TransactionalFs {
     readonly readdirSync: typeof readdirSync;
     readonly copyFileSync: typeof copyFileSync;
 }
+/** Shared path boundary for install/update and doctor/init writes. */
+export declare function safeManagedPath(projectRoot: string, relative: string): {
+    normalized: string;
+    target: string;
+};
 /**
  * Atomically reconcile an explicit cross-directory managed set. `removePaths`
  * must come from trusted metadata; this function never scans or uses globs.
  */
-export declare function executeManagedReconcile(projectRoot: string, writes: Readonly<Record<string, string | Uint8Array>>, removePaths: readonly string[], fs_: TransactionalFsWithCopy): void;
+export declare function executeManagedReconcile(projectRoot: string, writes: Readonly<Record<string, string | Uint8Array>>, removePaths: readonly string[], fs_: TransactionalFsWithCopy, options?: {
+    readonly expectedText?: Readonly<Record<string, string | undefined>>;
+    readonly expectedSha256?: Readonly<Record<string, string | undefined>>;
+}): void;
+/** Recover an interrupted process while preserving any independently edited file.
+ * Must run under the same project lock as reconcile. Invalid journals fail closed.
+ * This covers process termination, not power loss or a hostile filesystem.
+ */
+export declare function recoverManagedReconcile(projectRoot: string, fs_: TransactionalFsWithCopy): number;
 /** Pure list of install operations with expected checksums. */
 export declare function createInstallPlan(targetRoot: string, files: Readonly<Record<string, string | Uint8Array>>): InstallPlan;
 /** Create a deterministic ZIP for delivery (fixed mtime). */
@@ -68,9 +82,9 @@ export declare function executeGeneratedFiles(files: readonly {
  * the output directory is never left in a partial state.
  *
  * The set of CLI-managed paths is determined by the `files` argument. Any file
- * that already exists in outputDir but is NOT in that set is considered
- * user-owned and is preserved. Older CLI-managed files are identified by the
- * generated-file header and are intentionally not restored.
+ * that already exists in outputDir is considered user-owned and is preserved.
+ * This compatibility writer has no ownership metadata, so it refuses to
+ * replace an existing path. Production generation uses managed reconciliation.
  */
 export declare function executeGeneratedFilesDir(files: readonly {
     path: string;
@@ -103,6 +117,12 @@ export type DownloadResult = {
  * Download an artifact. HTTPS only, optional host allowlist, bounded redirects,
  * timeout, byte limit. Abort and temporary-file cleanup are handled by the
  * caller via the injected fetch/signal.
+ *
+ * Redirect policy: unlike the API descriptor handshake (which uses
+ * `redirect: "error"`), payload downloads intentionally follow a bounded number
+ * of redirects because code/metadata archives are served from CDNs that 3xx to
+ * a signed object host; the destination host is re-checked against the
+ * allowlist on every hop.
  */
 export declare function downloadArtifact(url: string, limits: DownloadLimits, deps?: {
     fetchFn?: typeof fetch;