@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/skill/__tests__/artifact-storage.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Pins the skill artifact store against Go's artifact_storage_test.go:
+ * path layout ({root}/skills/{hash}.zip — cutover inherits Go-written
+ * directories), permissions, traversal-guarded reads, and the dedupe
+ * surface (exists/getStorageKey). Since O5 the store is the domain port
+ * over the local blob driver — the assertions are UNCHANGED from the
+ * pre-reconciliation class on purpose: they are the byte-identity proof.
+ */
+import { mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { LocalArtifactStorage } from "../../../artifactstorage/artifact-storage.js";
+import {
+  ArtifactNotFoundError,
+  newSkillArtifactStorage,
+} from "../storage/artifact-storage.js";
+import type { SkillArtifactStorage } from "../storage/artifact-storage.js";
+
+const HASH = "a".repeat(64);
+const DATA = new TextEncoder().encode("zip bytes");
+
+let dir: string;
+let storage: SkillArtifactStorage;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), "skill-artifact-test-"));
+  // Mirrors the compose local arm (boot/compose.ts): skills/ boot-created
+  // 0755 (the Go layout invariant), the driver rooted at the storage path,
+  // the port owning keys and the not-found vocabulary.
+  mkdirSync(path.join(dir, "skills"), { recursive: true, mode: 0o755 });
+  storage = newSkillArtifactStorage(new LocalArtifactStorage(dir, ""));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("skill artifact store over the local driver", () => {
+  it("stores under skills/{hash}.zip — a LITERAL forward-slash key on every platform — and round-trips the bytes", async () => {
+    const key = await storage.store(HASH, DATA);
+    expect(key).toBe(`skills/${HASH}.zip`);
+    expect(await storage.get(key)).toEqual(Buffer.from(DATA));
+  });
+
+  it("writes artifacts owner-only (0600) under a 0755 directory", async () => {
+    const key = await storage.store(HASH, DATA);
+    const mode = statSync(path.join(dir, key)).mode & 0o777;
+    expect(mode).toBe(0o600);
+    const dirMode = statSync(path.join(dir, "skills")).mode & 0o777;
+    expect(dirMode).toBe(0o755);
+  });
+
+  it("reports existence by hash for dedupe", async () => {
+    expect(await storage.exists(HASH)).toBe(false);
+    await storage.store(HASH, DATA);
+    expect(await storage.exists(HASH)).toBe(true);
+  });
+
+  it("stats size without loading", async () => {
+    const key = await storage.store(HASH, DATA);
+    expect(await storage.size(key)).toBe(DATA.length);
+  });
+
+  it("answers not-found for a missing key", async () => {
+    await expect(storage.get("skills/missing.zip")).rejects.toThrow(
+      new ArtifactNotFoundError("skills/missing.zip").message,
+    );
+    await expect(storage.size("skills/missing.zip")).rejects.toThrow(
+      "artifact not found: skills/missing.zip",
+    );
+  });
+
+  it("treats traversal keys as missing artifacts, never reading escaped paths", async () => {
+    for (const key of ["../../etc/passwd", "skills/../../secret", "/etc/passwd"]) {
+      await expect(storage.get(key)).rejects.toThrow(`artifact not found: ${key}`);
+      await expect(storage.size(key)).rejects.toThrow(`artifact not found: ${key}`);
+    }
+  });
+});

package/src/domain/skill/__tests__/frontmatter.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Pins frontmatter parsing against Go's frontmatter_test.go table: the
+ * delimiter rules, required-name enforcement, and the kebab-case /
+ * dot-scoped name pattern. Error copy is wire-visible teaching text — the
+ * assertions check the load-bearing first lines.
+ */
+import { describe, expect, it } from "vitest";
+
+import { parseFrontmatter } from "../storage/frontmatter.js";
+
+function skillMd(frontmatter: string, body = "# Title"): string {
+  return `---\n${frontmatter}\n---\n${body}`;
+}
+
+describe("parseFrontmatter", () => {
+  it("parses name, description, and version", () => {
+    const fm = parseFrontmatter(
+      skillMd("name: web-scraper\ndescription: Scrapes pages\nversion: 1.0.0"),
+    );
+    expect(fm).toEqual({
+      name: "web-scraper",
+      description: "Scrapes pages",
+      version: "1.0.0",
+    });
+  });
+
+  it("accepts dot-scoped namespace names", () => {
+    expect(
+      parseFrontmatter(skillMd("name: platform.planton-architecture")).name,
+    ).toBe("platform.planton-architecture");
+  });
+
+  it("defaults description and version to empty", () => {
+    const fm = parseFrontmatter(skillMd("name: calculator"));
+    expect(fm.description).toBe("");
+    expect(fm.version).toBe("");
+  });
+
+  it("rejects empty content", () => {
+    expect(() => parseFrontmatter("")).toThrow("SKILL.md is empty");
+  });
+
+  it("rejects content that does not start with ---", () => {
+    expect(() => parseFrontmatter("# No frontmatter")).toThrow(
+      "SKILL.md must start with YAML frontmatter (---)",
+    );
+  });
+
+  it("rejects unclosed frontmatter", () => {
+    expect(() => parseFrontmatter("---\nname: x")).toThrow(
+      "SKILL.md frontmatter is not closed (missing closing ---)",
+    );
+  });
+
+  it("rejects empty frontmatter", () => {
+    expect(() => parseFrontmatter("---\n---\n# Body")).toThrow(
+      "SKILL.md has empty frontmatter",
+    );
+  });
+
+  it("rejects a missing name field", () => {
+    expect(() => parseFrontmatter(skillMd("description: no name here"))).toThrow(
+      "SKILL.md is missing required 'name' field in YAML frontmatter",
+    );
+  });
+
+  it("rejects malformed YAML", () => {
+    expect(() => parseFrontmatter(skillMd("name: [unclosed"))).toThrow(
+      "failed to parse YAML frontmatter",
+    );
+  });
+
+  it("rejects duplicated mapping keys (yaml.v3 and js-yaml both refuse)", () => {
+    expect(() => parseFrontmatter(skillMd("name: a\nname: b"))).toThrow(
+      "failed to parse YAML frontmatter",
+    );
+  });
+
+  it("rejects a BOM'd first line — Go's TrimSpace does not strip U+FEFF (#8 parity review)", () => {
+    expect(() => parseFrontmatter(`\uFEFF${skillMd("name: bom-skill")}`)).toThrow(
+      "SKILL.md must start with YAML frontmatter (---)",
+    );
+  });
+
+  it("accepts Unicode-whitespace-padded delimiters — Go trims the full White_Space set", () => {
+    // U+2000 (en quad) is White_Space: Go's TrimSpace reduces the line to
+    // "---" and accepts the file; the port must agree.
+    const fm = parseFrontmatter(`\u2000---\u2000\nname: padded-skill\n\u3000---\n# Body`);
+    expect(fm.name).toBe("padded-skill");
+  });
+
+  it("reports a first line over the 64KB scanner cap as empty — Go's !Scan() arm, bug-for-bug", () => {
+    const longFirstLine = "x".repeat(64 * 1024 + 1);
+    expect(() => parseFrontmatter(`${longFirstLine}\n---\nname: a\n---`)).toThrow(
+      "SKILL.md is empty",
+    );
+  });
+
+  it("reports an over-cap line INSIDE the frontmatter as the scanner error, beating 'not closed'", () => {
+    const longLine = `description: ${"y".repeat(64 * 1024)}`;
+    expect(() => parseFrontmatter(`---\nname: a\n${longLine}\n---`)).toThrow(
+      "error reading SKILL.md content: bufio.Scanner: token too long",
+    );
+  });
+
+  const badNames = [
+    "Web-Scraper", // uppercase
+    "web scraper", // space
+    "-leading", // leading separator
+    "trailing-", // trailing separator
+    "double--hyphen", // consecutive separators
+    "dot..dot", // consecutive dots
+    ".leading-dot",
+    "trailing-dot.",
+    "under_score",
+  ];
+  for (const name of badNames) {
+    it(`rejects the invalid name ${JSON.stringify(name)}`, () => {
+      expect(() => parseFrontmatter(skillMd(`name: ${JSON.stringify(name)}`))).toThrow(
+        `invalid skill name '${name}' in SKILL.md`,
+      );
+    });
+  }
+});

package/src/domain/skill/__tests__/prefilter.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Pins the safearchive-parity pre-filter (DD-001) against the behaviors
+ * read from safearchive's source at the go.mod-pinned version: sanitizer
+ * tests (sanitizer_nix_test.go), applyMagic's skip/shadow order, and the
+ * archive/zip mode-decode rules. Fixtures are byte-crafted with the shared
+ * builder so entry attributes are exactly what a real archive carries.
+ */
+import { describe, expect, it } from "vitest";
+
+import { parseZipStructure } from "@stigmer/zip-structure";
+import { buildZip } from "@stigmer/zip-structure/testing";
+
+import {
+  applyEntryPrefilter,
+  entryTypeBits,
+  hasWindowsShortFilenames,
+  sanitizePath,
+} from "../storage/prefilter.js";
+
+// versionMadeBy high byte 3 = Unix creator; POSIX mode rides the attribute
+// high 16 bits (how zip writers encode symlinks and special files).
+const UNIX_CREATOR = 0x0314;
+const symlinkAttrs = (0o120777 << 16) >>> 0;
+const charDeviceAttrs = (0o020644 << 16) >>> 0;
+const fifoAttrs = (0o010644 << 16) >>> 0;
+const regularAttrs = (0o100644 << 16) >>> 0;
+
+describe("sanitizePath (safearchive sanitizer.SanitizePath)", () => {
+  // Table from sanitizer_nix_test.go plus the arms the gate leans on.
+  const cases: Array<[string, string]> = [
+    ["some/thing", "some/thing"],
+    ["../../some/thing", "some/thing"],
+    ["..\\..\\some\\thing", "some/thing"],
+    ["/rooted/path", "rooted/path"],
+    ["../SKILL.md", "SKILL.md"],
+    ["a/../b", "b"],
+    ["a//b", "a/b"],
+    ["a/./b", "a/b"],
+    ["..", ""],
+    ["/", ""],
+    ["", ""],
+  ];
+  for (const [input, expected] of cases) {
+    it(`sanitizes ${JSON.stringify(input)} to ${JSON.stringify(expected)}`, () => {
+      expect(sanitizePath(input)).toBe(expected);
+    });
+  }
+
+  it("preserves a trailing separator when the result is non-empty", () => {
+    expect(sanitizePath("dir/")).toBe("dir/");
+    expect(sanitizePath("..\\dir\\")).toBe("dir/");
+    expect(sanitizePath("/")).toBe("");
+  });
+});
+
+describe("hasWindowsShortFilenames", () => {
+  it("detects 8.3-style markers in any path component", () => {
+    expect(hasWindowsShortFilenames("DOWNLO~1/file.txt")).toBe(true);
+    expect(hasWindowsShortFilenames("dir/FOOOOO~1.JPG")).toBe(true);
+    expect(hasWindowsShortFilenames("dir\\1(3)~1.PNG")).toBe(true);
+  });
+
+  it("passes ordinary names, including tildes without digits", () => {
+    expect(hasWindowsShortFilenames("references/schema.md")).toBe(false);
+    expect(hasWindowsShortFilenames("notes~draft.md")).toBe(false);
+  });
+});
+
+describe("entryTypeBits (archive/zip FileHeader.Mode decode)", () => {
+  function entryWith(versionMadeBy: number, externalAttributes: number) {
+    const zip = buildZip([
+      { name: "x", content: "x", versionMadeBy, externalAttributes },
+    ]);
+    return parseZipStructure(zip)[0]!;
+  }
+
+  it("decodes Unix symlink and special-file types", () => {
+    expect(entryTypeBits(entryWith(UNIX_CREATOR, symlinkAttrs))).toEqual({
+      isSymlink: true,
+      isSpecial: false,
+    });
+    expect(entryTypeBits(entryWith(UNIX_CREATOR, charDeviceAttrs))).toEqual({
+      isSymlink: false,
+      isSpecial: true,
+    });
+    expect(entryTypeBits(entryWith(UNIX_CREATOR, fifoAttrs))).toEqual({
+      isSymlink: false,
+      isSpecial: true,
+    });
+    expect(entryTypeBits(entryWith(UNIX_CREATOR, regularAttrs))).toEqual({
+      isSymlink: false,
+      isSpecial: false,
+    });
+  });
+
+  it("never decodes symlink/special for FAT creators — MSDOS attrs cannot express them", () => {
+    // The same attribute BITS under a FAT creator (versionMadeBy 20) are
+    // FAT attributes, not a POSIX mode.
+    expect(entryTypeBits(entryWith(20, symlinkAttrs))).toEqual({
+      isSymlink: false,
+      isSpecial: false,
+    });
+  });
+});
+
+describe("applyEntryPrefilter (safearchive applyMagic)", () => {
+  it("sanitizes names — a traversal-shaped SKILL.md becomes root SKILL.md", () => {
+    const zip = buildZip([{ name: "../SKILL.md", content: "# via traversal" }]);
+    const filtered = applyEntryPrefilter(parseZipStructure(zip));
+    expect(filtered.map((f) => f.name)).toEqual(["SKILL.md"]);
+  });
+
+  it("drops entries with Windows 8.3-style components", () => {
+    const zip = buildZip([
+      { name: "SKILL.md", content: "# ok" },
+      { name: "DOWNLO~1/asset.png", content: "x" },
+    ]);
+    const filtered = applyEntryPrefilter(parseZipStructure(zip));
+    expect(filtered.map((f) => f.name)).toEqual(["SKILL.md"]);
+  });
+
+  it("drops entries shadowed by an earlier symlink, case-insensitively; the symlink entry itself stays", () => {
+    const zip = buildZip([
+      {
+        name: "Link",
+        content: "target",
+        versionMadeBy: UNIX_CREATOR,
+        externalAttributes: symlinkAttrs,
+      },
+      { name: "link/inside.txt", content: "smuggled" },
+      { name: "safe/file.txt", content: "ok" },
+    ]);
+    const filtered = applyEntryPrefilter(parseZipStructure(zip));
+    expect(filtered.map((f) => f.name)).toEqual(["Link", "safe/file.txt"]);
+  });
+
+  it("drops special-file entries (devices, pipes)", () => {
+    const zip = buildZip([
+      { name: "SKILL.md", content: "# ok" },
+      {
+        name: "dev-node",
+        content: "",
+        versionMadeBy: UNIX_CREATOR,
+        externalAttributes: charDeviceAttrs,
+      },
+    ]);
+    const filtered = applyEntryPrefilter(parseZipStructure(zip));
+    expect(filtered.map((f) => f.name)).toEqual(["SKILL.md"]);
+  });
+
+  it("keeps regular Unix-creator entries untouched", () => {
+    const zip = buildZip([
+      {
+        name: "SKILL.md",
+        content: "# ok",
+        versionMadeBy: UNIX_CREATOR,
+        externalAttributes: regularAttrs,
+      },
+    ]);
+    const filtered = applyEntryPrefilter(parseZipStructure(zip));
+    expect(filtered.map((f) => f.name)).toEqual(["SKILL.md"]);
+  });
+});

package/src/domain/skill/__tests__/push-degradation.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Pins ArchiveCurrentSkill's safe-degradation arms (Go push_test.go's
+ * failing-store cases) at step level — the composed suite cannot make the
+ * real store fail selectively:
+ *
+ *   - archive (saveAudit) failure clears status.version_hash AND
+ *     metadata.version.id — the persisted head never references an
+ *     unresolvable audit entry; the push itself still succeeds;
+ *   - tag assignment (setAuditTag) failure clears the live spec.tag — the
+ *     head never advertises a tag the audit column cannot resolve;
+ *   - an UNEXPECTED repoint-lookup failure degrades to archiving anyway (a
+ *     possible duplicate row beats a failed push);
+ *   - already-archived content repoints: saveAudit is never called, the
+ *     tag assignment still runs (re-pushing under a new tag is skills'
+ *     only retag path).
+ */
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { PushSkillRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import { AuditNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+import { SKILL_KEY, newArchiveCurrentSkillStep } from "../push.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const HASH = "b".repeat(64);
+
+interface FakeAuditStore {
+  getAuditByHashError: Error | undefined;
+  saveAuditError: Error | undefined;
+  setAuditTagError: Error | undefined;
+  saveAuditCalls: number;
+  setAuditTagCalls: Array<{ versionHash: string; tag: string }>;
+}
+
+/** A store exposing ONLY the members the step touches; the cast is the seam. */
+function fakeStore(overrides?: Partial<FakeAuditStore>): {
+  store: Store;
+  state: FakeAuditStore;
+} {
+  const state: FakeAuditStore = {
+    getAuditByHashError: new AuditNotFoundError("not archived"),
+    saveAuditError: undefined,
+    setAuditTagError: undefined,
+    saveAuditCalls: 0,
+    setAuditTagCalls: [],
+    ...overrides,
+  };
+  const store = {
+    async getAuditByHash(): Promise<never> {
+      if (state.getAuditByHashError !== undefined) {
+        throw state.getAuditByHashError;
+      }
+      return undefined as never; // "found" — repoint path
+    },
+    async saveAudit(): Promise<void> {
+      state.saveAuditCalls += 1;
+      if (state.saveAuditError !== undefined) {
+        throw state.saveAuditError;
+      }
+    },
+    async setAuditTag(
+      _k: unknown,
+      _r: unknown,
+      versionHash: string,
+      tag: string,
+    ): Promise<void> {
+      state.setAuditTagCalls.push({ versionHash, tag });
+      if (state.setAuditTagError !== undefined) {
+        throw state.setAuditTagError;
+      }
+    },
+  } as unknown as Store;
+  return { store, state };
+}
+
+function contextWithSkill(tag: string) {
+  const ctx = new RequestContext(
+    PushSkillRequestSchema,
+    create(PushSkillRequestSchema, {}),
+    testCallerIdentity(),
+    ApiResourceKind.skill,
+  );
+  const skill = create(SkillSchema, {
+    metadata: { id: "skl_test", org: "acme", version: { id: HASH } },
+    spec: { tag },
+    status: { versionHash: HASH },
+  });
+  ctx.set(SKILL_KEY, skill);
+  return { ctx, skill };
+}
+
+describe("ArchiveCurrentSkill — safe degradation", () => {
+  it("archive failure clears the version hash and version id; the step does not throw", async () => {
+    const { store } = fakeStore({ saveAuditError: new Error("disk full") });
+    const { ctx, skill } = contextWithSkill("stable");
+
+    await newArchiveCurrentSkillStep(store, silentLogger).execute(ctx);
+
+    expect(skill.status?.versionHash).toBe("");
+    expect(skill.metadata?.version?.id).toBe("");
+    // The tag assignment never ran — there is no archived row to hold it.
+    expect(skill.spec?.tag).toBe("stable");
+  });
+
+  it("tag-assignment failure clears the live spec.tag; the archived row stands", async () => {
+    const { store, state } = fakeStore({
+      setAuditTagError: new Error("tag column locked"),
+    });
+    const { ctx, skill } = contextWithSkill("stable");
+
+    await newArchiveCurrentSkillStep(store, silentLogger).execute(ctx);
+
+    expect(state.saveAuditCalls).toBe(1);
+    expect(skill.spec?.tag).toBe("");
+    expect(skill.status?.versionHash).toBe(HASH);
+  });
+
+  it("an unexpected repoint-lookup failure degrades to archiving anyway", async () => {
+    const { store, state } = fakeStore({
+      getAuditByHashError: new Error("io error, not AuditNotFound"),
+    });
+    const { ctx, skill } = contextWithSkill("");
+
+    await newArchiveCurrentSkillStep(store, silentLogger).execute(ctx);
+
+    expect(state.saveAuditCalls).toBe(1);
+    expect(skill.status?.versionHash).toBe(HASH);
+  });
+
+  it("already-archived content repoints without a new row; the tag still moves", async () => {
+    const { store, state } = fakeStore({ getAuditByHashError: undefined });
+    const { ctx } = contextWithSkill("stable");
+
+    await newArchiveCurrentSkillStep(store, silentLogger).execute(ctx);
+
+    expect(state.saveAuditCalls).toBe(0);
+    expect(state.setAuditTagCalls).toEqual([
+      { versionHash: HASH, tag: "stable" },
+    ]);
+  });
+
+  it("a skill with no version hash is a no-op (nothing to archive)", async () => {
+    const { store, state } = fakeStore();
+    const ctx = new RequestContext(
+      PushSkillRequestSchema,
+      create(PushSkillRequestSchema, {}),
+      testCallerIdentity(),
+      ApiResourceKind.skill,
+    );
+    ctx.set(
+      SKILL_KEY,
+      create(SkillSchema, { metadata: { id: "skl_x" }, spec: {}, status: {} }),
+    );
+
+    await newArchiveCurrentSkillStep(store, silentLogger).execute(ctx);
+    expect(state.saveAuditCalls).toBe(0);
+    expect(state.setAuditTagCalls).toEqual([]);
+  });
+});