@stigmer/cli 3.12.1 → 3.12.2

package/src/resources/skill.test.ts

@@ -1,13 +1,13 @@
 // Unit tests for the skill packaging layer: SKILL.md frontmatter parsing, the
 // ignore-filtered zip walk, dry-run analysis, and byte/hash formatting.
 
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import type { Stigmer } from "@stigmer/sdk";
-import { unzipSync } from "fflate";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { unzipSync, zipSync } from "fflate";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { classify, ExitCode } from "../errors/index.js";
 import {
   analyzeDryRun,
@@ -17,6 +17,8 @@ import {
   parseSkillMetadata,
   parseVisibility,
   pushSkill,
+  pushSkillFromArchive,
+  readSkillArchive,
   shortHash,
 } from "./skill.js";
 
@@ -113,12 +115,17 @@ describe("parseVisibility", () => {
 
 // A minimal fake of the SDK surface pushSkill touches: skill.push + skill.updateVisibility.
 function fakeClient(pushMeta: { id?: string; visibility?: ApiResourceVisibility }) {
-  const calls = { push: 0, updateVisibility: [] as Array<{ resourceId: string; visibility: ApiResourceVisibility }> };
+  const calls = {
+    push: 0,
+    pushedArtifacts: [] as Uint8Array[],
+    updateVisibility: [] as Array<{ resourceId: string; visibility: ApiResourceVisibility }>,
+  };
   const skillMessage = { metadata: { ...pushMeta } };
   const client = {
     skill: {
-      async push() {
+      async push(request?: { artifact?: Uint8Array }) {
         calls.push++;
+        if (request?.artifact !== undefined) calls.pushedArtifacts.push(request.artifact);
         return skillMessage;
       },
       async updateVisibility(input: { resourceId: string; visibility: ApiResourceVisibility }) {
@@ -199,6 +206,113 @@ describe("createSkillZip", () => {
   });
 });
 
+describe("createSkillZip determinism", () => {
+  // Version identity is the server-side SHA-256 of the zip bytes, so identical
+  // content must produce identical bytes no matter when or where it was
+  // checked out (stigmer/stigmer#671). Distinct source mtimes model the fresh
+  // CI checkout; distinct wall-clock runs are inherent to running twice.
+  it("produces byte-identical zips for identical content across mtimes and wall-clock time", () => {
+    const otherDir = mkdtempSync(join(tmpdir(), "skill-test-b-"));
+    vi.useFakeTimers();
+    try {
+      for (const d of [dir, otherDir]) {
+        writeFileSync(join(d, "SKILL.md"), SKILL_MD);
+        mkdirSync(join(d, "references"));
+        writeFileSync(join(d, "references", "guide.md"), "# Guide\n");
+      }
+      // Backdate one copy: same content, different filesystem timestamps
+      // (models a fresh CI checkout).
+      const past = new Date("2020-06-15T12:00:00Z");
+      utimesSync(join(otherDir, "SKILL.md"), past, past);
+      utimesSync(join(otherDir, "references", "guide.md"), past, past);
+
+      // Advance the clock between runs: without a pinned mtime, fflate stamps
+      // zip-creation time into every entry (DOS 2-second granularity), so two
+      // pushes minutes apart would differ even from the same directory.
+      vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+      const a = createSkillZip(dir, NO_IGNORE).bytes;
+      vi.setSystemTime(new Date("2026-01-01T00:05:00Z"));
+      const b = createSkillZip(otherDir, NO_IGNORE).bytes;
+      expect(Buffer.from(a).equals(Buffer.from(b))).toBe(true);
+    } finally {
+      vi.useRealTimers();
+      rmSync(otherDir, { recursive: true, force: true });
+    }
+  });
+
+  it("changes bytes when content changes", () => {
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    const before = createSkillZip(dir, NO_IGNORE).bytes;
+    writeFileSync(join(dir, "extra.md"), "new content\n");
+    const after = createSkillZip(dir, NO_IGNORE).bytes;
+    expect(Buffer.from(before).equals(Buffer.from(after))).toBe(false);
+  });
+});
+
+describe("readSkillArchive", () => {
+  function writeArchive(files: Record<string, string>): string {
+    const zipped = zipSync(
+      Object.fromEntries(Object.entries(files).map(([p, c]) => [p, new TextEncoder().encode(c)])),
+    );
+    const archivePath = join(dir, "skill.zip");
+    writeFileSync(archivePath, zipped);
+    return archivePath;
+  }
+
+  it("accepts an archive with a root SKILL.md and reports entry stats", () => {
+    const archivePath = writeArchive({
+      "SKILL.md": SKILL_MD,
+      "references/guide.md": "# Guide\n",
+    });
+    const archive = readSkillArchive(archivePath);
+    expect(archive.meta.name).toBe("my-skill");
+    expect(archive.fileCount).toBe(2);
+    expect(archive.totalSize).toBeGreaterThan(0);
+  });
+
+  it("rejects an archive whose SKILL.md is only nested (root-only contract, DD-018)", () => {
+    const archivePath = writeArchive({ "my-skill/SKILL.md": SKILL_MD });
+    expect(() => readSkillArchive(archivePath)).toThrow(/root of/);
+  });
+
+  it("rejects a file that is not a ZIP archive", () => {
+    const archivePath = join(dir, "not-a-zip.zip");
+    writeFileSync(archivePath, "plain text");
+    expect(() => readSkillArchive(archivePath)).toThrow(/not a valid ZIP/);
+  });
+
+  it("rejects a missing file with a usage error", () => {
+    const err = (() => {
+      try {
+        readSkillArchive(join(dir, "absent.zip"));
+      } catch (e) {
+        return e;
+      }
+    })();
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+});
+
+describe("pushSkillFromArchive", () => {
+  it("uploads the archive bytes untouched (checksum parity) and applies declared visibility", async () => {
+    const zipped = zipSync({
+      "SKILL.md": new TextEncoder().encode("---\nname: my-skill\nvisibility: public\n---\n# S\n"),
+    });
+    const archivePath = join(dir, "skill.zip");
+    writeFileSync(archivePath, zipped);
+    const { client, calls } = fakeClient({ id: "skill-123", visibility: ApiResourceVisibility.visibility_private });
+
+    const result = await pushSkillFromArchive(client, archivePath, "stigmer", "", "release v1.2.3");
+
+    expect(calls.push).toBe(1);
+    expect(Buffer.from(calls.pushedArtifacts[0]).equals(Buffer.from(zipped))).toBe(true);
+    expect(calls.updateVisibility).toEqual([
+      { resourceId: "skill-123", visibility: ApiResourceVisibility.visibility_public },
+    ]);
+    expect(result.skillName).toBe("my-skill");
+  });
+});
+
 describe("analyzeDryRun", () => {
   it("reports counts and pattern sources without producing bytes", () => {
     writeFileSync(join(dir, "SKILL.md"), SKILL_MD);

package/src/resources/skill.ts

@@ -14,13 +14,24 @@ import { GitProvenanceSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { Stigmer } from "@stigmer/sdk";
-import { zipSync } from "fflate";
+import { strFromU8, unzipSync, zipSync } from "fflate";
 import { parse as parseYaml } from "yaml";
 import { UsageError } from "../errors/index.js";
 import { getGitBranchName, getGitCommit, getGitRemoteUrl, getGitRepoRoot } from "./git.js";
 import { createMatcher, REASON_TEXT, type Reason } from "./ignore/index.js";
 
 export const SKILL_FILE = "SKILL.md";
+
+// A skill version's identity is the server-side SHA-256 of the uploaded zip
+// bytes, so packaging must be a pure function of content — otherwise
+// re-pushing unchanged content registers a new version and the server's
+// unchanged-content no-op never fires (stigmer/stigmer#671). fflate stamps
+// zip-creation time into every entry when no mtime is given; pinning the DOS
+// epoch (the earliest representable zip timestamp) removes the only
+// byte-level variance. Local-field Date construction is deliberate: DOS
+// timestamps store wall-clock fields, so this encodes identically in every
+// timezone.
+const DETERMINISTIC_ZIP_MTIME = new Date(1980, 0, 1);
 // Kebab-case, optionally scoped with dot-separated namespaces (e.g.
 // "platform.planton-architecture"). Every segment must be alphanumeric, so no
 // leading/trailing/consecutive separators. The derived slug renders dots as hyphens.
@@ -102,7 +113,16 @@ export function parseSkillMetadata(dir: string): SkillMetadata {
   } catch (err) {
     throw new Error(`failed to read ${SKILL_FILE}: ${(err as Error).message}`);
   }
+  return parseSkillMetadataContent(content);
+}
 
+/**
+ * Parse SKILL.md content directly — the shared core behind the directory
+ * path (`parseSkillMetadata`) and the pre-packaged archive path
+ * (`pushSkillFromArchive`), where the content comes out of a zip entry
+ * rather than the filesystem.
+ */
+export function parseSkillMetadataContent(content: string): SkillMetadata {
   const frontmatter = extractFrontmatter(content);
   const parsed = (parseYaml(frontmatter) ?? {}) as Record<string, unknown>;
   const name = typeof parsed.name === "string" ? parsed.name : "";
@@ -233,7 +253,7 @@ export function createSkillZip(
   };
   walk(dir, "");
 
-  const bytes = zipSync(files, { level: 6 });
+  const bytes = zipSync(files, { level: 6, mtime: DETERMINISTIC_ZIP_MTIME });
   return { bytes, stats };
 }
 
@@ -373,6 +393,92 @@ export async function pushSkillFromClone(
   return toResult(applied, name, params.message, stats.totalSize, visibility);
 }
 
+/** A validated pre-packaged skill archive (`--archive`), ready to upload. */
+export interface SkillArchive {
+  /** The archive file's exact bytes — uploaded untouched. */
+  readonly bytes: Uint8Array;
+  /** Metadata parsed from the archive's root SKILL.md. */
+  readonly meta: SkillMetadata;
+  /** Number of file entries (directory markers excluded). */
+  readonly fileCount: number;
+  /** Total uncompressed size of all file entries, in bytes. */
+  readonly totalSize: number;
+}
+
+/**
+ * Read and validate a pre-packaged skill archive.
+ *
+ * Client-side validation is deliberately minimal — root SKILL.md present and
+ * frontmatter parses (the same contract the console's upload preview checks);
+ * the server remains the authoritative validator. The unzip filter inflates
+ * ONLY SKILL.md: entry metadata is enough for the count/size summary, and
+ * validation must not pay for decompressing a large artifact.
+ */
+export function readSkillArchive(archivePath: string): SkillArchive {
+  let raw: Buffer;
+  try {
+    raw = readFileSync(archivePath);
+  } catch (err) {
+    throw new UsageError(`failed to read archive ${archivePath}: ${(err as Error).message}`);
+  }
+  const bytes = new Uint8Array(raw);
+
+  let fileCount = 0;
+  let totalSize = 0;
+  let unzipped: Record<string, Uint8Array>;
+  try {
+    unzipped = unzipSync(bytes, {
+      filter: (info) => {
+        if (!info.name.endsWith("/")) {
+          fileCount++;
+          totalSize += info.originalSize;
+        }
+        return info.name === SKILL_FILE;
+      },
+    });
+  } catch (err) {
+    throw new UsageError(`${archivePath} is not a valid ZIP archive: ${(err as Error).message}`);
+  }
+
+  const skillMd = unzipped[SKILL_FILE];
+  if (skillMd === undefined) {
+    throw new UsageError(
+      `${SKILL_FILE} not found at the root of ${archivePath}\n\n` +
+        `A skill archive must contain ${SKILL_FILE} at its root (not inside a directory) defining the skill interface`,
+    );
+  }
+
+  return { bytes, meta: parseSkillMetadataContent(strFromU8(skillMd)), fileCount, totalSize };
+}
+
+/**
+ * Push a pre-packaged skill archive as-is (`--archive`).
+ *
+ * The bytes are uploaded untouched, so the engine's version hash is the
+ * SHA-256 of the file on disk — release pipelines that publish checksums get
+ * engine version identities that match them (stigmer/stigmer#671). Git
+ * provenance is deliberately omitted: the archive was built elsewhere, so the
+ * local checkout says nothing about the artifact's origin.
+ */
+export async function pushSkillFromArchive(
+  client: Stigmer,
+  archivePath: string,
+  org: string,
+  tag: string,
+  message: string,
+): Promise<PushResult> {
+  const archive = readSkillArchive(archivePath);
+  const request = create(PushSkillRequestSchema, {
+    org,
+    artifact: archive.bytes,
+    tag: tag === "" ? "latest" : tag,
+    message,
+  });
+  const response = await client.skill.push(request);
+  const applied = await applyDeclaredVisibility(client, response, archive.meta.visibility);
+  return toResult(applied, archive.meta.name, message, archive.totalSize, archive.meta.visibility);
+}
+
 /**
  * Apply the SKILL.md-declared visibility after a push. The push RPC carries
  * artifact + provenance but not access level (visibility is metadata, not part