@stigmer/cli 3.0.8

package/src/resources/run/workspace.test.ts

@@ -0,0 +1,93 @@
+// Unit tests for workspace flag parsing: git vs local variant selection, SSH
+// rejection, branch/commit applicability rules, name derivation, and duplicate
+// detection.
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { localWorkspaceRoots, parseWorkspaceEntries, workspaceNames } from "./workspace.js";
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "ws-test-"));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("parseWorkspaceEntries (git)", () => {
+  it("builds a GitRepoSource with branch and commit", () => {
+    const entries = parseWorkspaceEntries(["https://github.com/acme/my-app.git"], "main", "abc123");
+    expect(entries).toHaveLength(1);
+    expect(entries[0].name).toBe("my-app");
+    const source = entries[0].source;
+    expect(source?.source.case).toBe("gitRepo");
+    if (source?.source.case === "gitRepo") {
+      expect(source.source.value.url).toBe("https://github.com/acme/my-app.git");
+      expect(source.source.value.branch).toBe("main");
+      expect(source.source.value.commit).toBe("abc123");
+    }
+  });
+
+  it("derives the repo name from a URL without .git or trailing slash", () => {
+    expect(parseWorkspaceEntries(["https://github.com/acme/repo/"], "", "")[0].name).toBe("repo");
+  });
+
+  it("rejects SSH git URLs with HTTPS guidance", () => {
+    expect(() => parseWorkspaceEntries(["git@github.com:acme/x.git"], "", "")).toThrow(/SSH git URLs are not supported/);
+  });
+});
+
+describe("parseWorkspaceEntries (local)", () => {
+  it("builds a LocalPathSource from an existing directory", () => {
+    const entries = parseWorkspaceEntries([dir], "", "");
+    expect(entries[0].name).toBe(basename(dir));
+    expect(entries[0].source?.source.case).toBe("localPath");
+    if (entries[0].source?.source.case === "localPath") {
+      expect(entries[0].source.source.value.path).toBe(dir);
+    }
+  });
+
+  it("rejects a non-existent local path", () => {
+    expect(() => parseWorkspaceEntries([join(dir, "missing")], "", "")).toThrow(/does not exist/);
+  });
+
+  it("rejects --branch/--commit on a local workspace", () => {
+    expect(() => parseWorkspaceEntries([dir], "main", "")).toThrow(/only valid with git workspace/);
+  });
+});
+
+describe("parseWorkspaceEntries (rules)", () => {
+  it("returns an empty list when no workspace is given", () => {
+    expect(parseWorkspaceEntries([], "", "")).toEqual([]);
+  });
+
+  it("rejects --branch/--commit without --workspace", () => {
+    expect(() => parseWorkspaceEntries([], "main", "")).toThrow(/require --workspace/);
+  });
+
+  it("rejects --branch/--commit with more than one workspace", () => {
+    expect(() =>
+      parseWorkspaceEntries(["https://github.com/a/b.git", "https://github.com/c/d.git"], "main", ""),
+    ).toThrow(/single git workspace/);
+  });
+
+  it("rejects duplicate derived names", () => {
+    expect(() =>
+      parseWorkspaceEntries(["https://github.com/a/dup.git", "https://github.com/b/dup.git"], "", ""),
+    ).toThrow(/duplicate workspace name/);
+  });
+});
+
+describe("derived helpers", () => {
+  it("localWorkspaceRoots returns only local paths", () => {
+    const entries = parseWorkspaceEntries([dir, "https://github.com/a/b.git"], "", "");
+    expect(localWorkspaceRoots(entries)).toEqual([dir]);
+  });
+
+  it("workspaceNames returns every entry name", () => {
+    const entries = parseWorkspaceEntries([dir, "https://github.com/a/b.git"], "", "");
+    expect(workspaceNames(entries)).toEqual([basename(dir), "b"]);
+  });
+});

package/src/resources/run/workspace.ts

@@ -0,0 +1,171 @@
+// Workspace flag parsing for agent execution.
+//
+// Ports the Go CLI's run_workspace.go: turns repeatable `--workspace` values
+// (plus `--branch`/`--commit`) into WorkspaceEntry protos. A workspace is either
+// an HTTPS git repo (branch/commit allowed) or a local directory (branch/commit
+// rejected). SSH git URLs are rejected with HTTPS guidance, and `--branch`/
+// `--commit` only apply to a single git workspace.
+
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, resolve } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import {
+  GitRepoSourceSchema,
+  LocalPathSourceSchema,
+  type WorkspaceEntry,
+  WorkspaceEntrySchema,
+  type WorkspaceSource,
+  WorkspaceSourceSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+import { UsageError } from "../../errors/index.js";
+
+/**
+ * Convert `--workspace`/`--branch`/`--commit` flags into WorkspaceEntry protos.
+ * Returns an empty list when no workspace is requested. Mirrors Go's
+ * parseWorkspaceEntries, including the single-git-workspace rule for
+ * branch/commit and duplicate-name detection.
+ */
+export function parseWorkspaceEntries(
+  workspaces: readonly string[],
+  branch: string,
+  commit: string,
+): WorkspaceEntry[] {
+  if (workspaces.length === 0) {
+    if (branch !== "" || commit !== "") {
+      throw new UsageError("--branch and --commit require --workspace");
+    }
+    return [];
+  }
+
+  if (workspaces.length > 1 && (branch !== "" || commit !== "")) {
+    throw new UsageError("--branch and --commit are only valid with a single git workspace");
+  }
+
+  const entries: WorkspaceEntry[] = [];
+  const seenNames = new Map<string, string>(); // derived name -> original value
+  for (const ws of workspaces) {
+    const source = parseWorkspaceSource(ws, branch, commit);
+    const name = deriveEntryName(ws);
+    const prev = seenNames.get(name);
+    if (prev !== undefined) {
+      throw new UsageError(
+        `duplicate workspace name "${name}" derived from both "${prev}" and "${ws}"; ` +
+          "use distinct directory names or repository URLs",
+      );
+    }
+    seenNames.set(name, ws);
+    entries.push(create(WorkspaceEntrySchema, { name, source }));
+  }
+  return entries;
+}
+
+/**
+ * The absolute paths of any local (non-git) workspace roots. Attachment
+ * processing uses these to decide whether a file is workspace-relative (no
+ * upload) versus an upload. Mirrors Go's localWorkspaceRoots.
+ */
+export function localWorkspaceRoots(entries: readonly WorkspaceEntry[]): string[] {
+  const roots: string[] = [];
+  for (const entry of entries) {
+    if (entry.source?.source.case === "localPath") {
+      roots.push(entry.source.source.value.path);
+    }
+  }
+  return roots;
+}
+
+/** The derived display names of the workspace entries, for the session header. */
+export function workspaceNames(entries: readonly WorkspaceEntry[]): string[] {
+  return entries.map((entry) => entry.name);
+}
+
+// Mirrors Go's parseWorkspaceSource: variant selection (git vs local) plus the
+// branch/commit applicability rules and SSH rejection.
+function parseWorkspaceSource(workspace: string, branch: string, commit: string): WorkspaceSource {
+  if (isSshGitUrl(workspace)) {
+    throw new UsageError(
+      `SSH git URLs are not supported: ${workspace}\n\n` +
+        "Use HTTPS instead: https://github.com/org/repo",
+    );
+  }
+
+  if (isGitUrl(workspace)) {
+    return create(WorkspaceSourceSchema, {
+      source: { case: "gitRepo", value: create(GitRepoSourceSchema, { url: workspace, branch, commit }) },
+    });
+  }
+
+  if (branch !== "" || commit !== "") {
+    throw new UsageError("--branch and --commit are only valid with git workspace URLs (https://...)");
+  }
+  return parseLocalWorkspace(workspace);
+}
+
+// Resolve a local path, verify it is an existing directory, and wrap it as a
+// LocalPathSource. Mirrors Go's parseLocalWorkspace.
+function parseLocalWorkspace(path: string): WorkspaceSource {
+  const resolved = resolveLocalPath(path);
+  let isDir: boolean;
+  try {
+    isDir = statSync(resolved).isDirectory();
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === "ENOENT") throw new UsageError(`workspace path does not exist: ${resolved}`);
+    throw new UsageError(`cannot access workspace path ${resolved}: ${e.message}`);
+  }
+  if (!isDir) throw new UsageError(`workspace path is not a directory: ${resolved}`);
+
+  return create(WorkspaceSourceSchema, {
+    source: { case: "localPath", value: create(LocalPathSourceSchema, { path: resolved }) },
+  });
+}
+
+// A short identity for the entry: the repo name for git URLs, the directory
+// basename for local paths. Mirrors Go's deriveEntryName.
+function deriveEntryName(workspace: string): string {
+  if (isGitUrl(workspace)) return deriveGitRepoName(workspace);
+  return deriveLocalDirName(workspace);
+}
+
+// Last non-empty URL path segment, sans ".git". Mirrors Go's deriveGitRepoName.
+function deriveGitRepoName(rawUrl: string): string {
+  let path: string;
+  try {
+    path = new URL(rawUrl).pathname;
+  } catch {
+    throw new UsageError(`cannot parse git URL for name derivation: ${rawUrl}`);
+  }
+  path = path.replace(/\/+$/, "").replace(/\.git$/, "");
+  const segments = path.split("/");
+  for (let i = segments.length - 1; i >= 0; i--) {
+    if (segments[i] !== "") return segments[i];
+  }
+  throw new UsageError(`cannot derive workspace name from URL: ${rawUrl}`);
+}
+
+// Directory basename of the resolved absolute path. Mirrors Go's
+// deriveLocalDirName — "." resolves to the CWD basename, not ".".
+function deriveLocalDirName(path: string): string {
+  const resolved = resolveLocalPath(path);
+  const name = basename(resolved);
+  if (name === "." || name === "/" || name === "") {
+    throw new UsageError(`cannot derive workspace name from path: ${path}`);
+  }
+  return name;
+}
+
+// Expand a leading "~/" and make the path absolute. Mirrors Go's resolveLocalPath.
+function resolveLocalPath(path: string): string {
+  let p = path;
+  if (p.startsWith("~/")) p = resolve(homedir(), p.slice(2));
+  return isAbsolute(p) ? p : resolve(p);
+}
+
+function isGitUrl(s: string): boolean {
+  return s.startsWith("https://") || s.startsWith("http://");
+}
+
+function isSshGitUrl(s: string): boolean {
+  return s.startsWith("git@");
+}

package/src/resources/search.ts

@@ -0,0 +1,53 @@
+// `search` dispatch: a relevance-ranked, cross-resource text query over the
+// unified SearchService. Only agents and workflows are search-indexed (matching
+// the Go CLI). Results render identically to `list` (the shared SEARCH_TABLE),
+// with a pagination footer the command appends for human output.
+
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { SearchResultSchema } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import type { OutputFormat } from "../output/index.js";
+import { SEARCH_TABLE } from "./list.js";
+import { renderCollection } from "./render.js";
+
+export interface SearchParams {
+  /** Organization scope. Empty searches across all accessible orgs (incl. public). */
+  readonly org: string;
+  /** Exclude public/platform resources, restricting to the caller's own. */
+  readonly excludePublic: boolean;
+  /** 1-indexed page number. */
+  readonly page: number;
+  /** Results per page. */
+  readonly pageSize: number;
+}
+
+export interface SearchOutcome {
+  /** Rendered entries (table grid, or protojson array for json/yaml). */
+  readonly rendered: string;
+  readonly page: number;
+  readonly totalPages: number;
+  readonly totalCount: number;
+}
+
+export async function searchResources(
+  client: Stigmer,
+  kind: ApiResourceKind,
+  query: string,
+  params: SearchParams,
+  format: OutputFormat,
+): Promise<SearchOutcome> {
+  const response = await client.search.query({
+    kinds: [kind],
+    query,
+    org: params.org,
+    excludePublic: params.excludePublic,
+    page: { num: params.page, size: params.pageSize },
+  });
+
+  return {
+    rendered: renderCollection(SearchResultSchema, response.entries, format, SEARCH_TABLE),
+    page: params.page,
+    totalPages: response.totalPages,
+    totalCount: response.totalCount,
+  };
+}

package/src/resources/session.test.ts

@@ -0,0 +1,48 @@
+import { create } from "@bufbuild/protobuf";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionListSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/io_pb";
+import { describe, expect, it } from "vitest";
+import { isSessionAlias, renderSessionList } from "./session.js";
+
+describe("isSessionAlias", () => {
+  it.each([
+    ["session", true],
+    ["sessions", true],
+    ["  Session ", true],
+    ["execution", false],
+    ["agent", false],
+  ])("%j -> %s", (type, expected) => {
+    expect(isSessionAlias(type)).toBe(expected);
+  });
+});
+
+describe("renderSessionList", () => {
+  const list = create(SessionListSchema, {
+    totalPages: 1,
+    entries: [
+      create(SessionSchema, {
+        metadata: { id: "ses_1" },
+        spec: { agentInstanceId: "agi_1", subject: "Fix the build" },
+      }),
+    ],
+  });
+  const result = { schema: SessionListSchema, message: list };
+
+  it("renders the full list envelope as protojson for json", () => {
+    const json = JSON.parse(renderSessionList(result, "json"));
+    expect(json.entries[0].metadata.id).toBe("ses_1");
+  });
+
+  it("renders a table with the session columns", () => {
+    const table = renderSessionList(result, "table");
+    expect(table).toContain("SESSION ID");
+    expect(table).toContain("ses_1");
+    expect(table).toContain("agi_1");
+    expect(table).toContain("Fix the build");
+  });
+
+  it("renders an empty notice for no sessions", () => {
+    const empty = { schema: SessionListSchema, message: create(SessionListSchema, {}) };
+    expect(renderSessionList(empty, "table").toLowerCase()).toContain("no sessions");
+  });
+});

package/src/resources/session.ts

@@ -0,0 +1,66 @@
+// `list sessions` support. Sessions, like executions, are runtime resources that
+// bypass the resource registry: there is no `get`/`create`/`delete session` in
+// the unified verbs, only a list. This module owns the alias predicate and the
+// list fetch so the command layer stays declarative.
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ListAgentExecutionsBySessionRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { ListSessionsRequestSchema, SessionListSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/io_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import type { OutputFormat } from "../output/index.js";
+import type { ResourceResult } from "./get-bindings.js";
+import { obj, renderListMessage, str, type TableShape } from "./render.js";
+
+// Mirrors Go's execution.MaxPageSize — fetch the whole session history in one
+// call (sessions don't accumulate enough executions to need pagination here).
+const MAX_EXECUTIONS_PAGE_SIZE = 100;
+
+/** Fetch a single session by ID (Go's session.GetFromBackend). */
+export async function getSessionById(client: Stigmer, sessionId: string): Promise<Session> {
+  return client.session.get(sessionId);
+}
+
+/**
+ * List a session's executions, newest-first (the backend's order, matching Go's
+ * execution.ListBySession). Returns the raw entries for resume to inspect.
+ */
+export async function listExecutionsBySession(client: Stigmer, sessionId: string): Promise<AgentExecution[]> {
+  const list = await client.agentExecution.listBySession(
+    create(ListAgentExecutionsBySessionRequestSchema, { sessionId, pageSize: MAX_EXECUTIONS_PAGE_SIZE }),
+  );
+  return list.entries;
+}
+
+/** True for the `session`/`sessions` type-alias family. */
+export function isSessionAlias(type: string): boolean {
+  const normalized = type.trim().toLowerCase();
+  return normalized === "session" || normalized === "sessions";
+}
+
+/** List sessions for the current context, paginated by `limit`. */
+export async function listSessions(client: Stigmer, limit: number): Promise<ResourceResult> {
+  const message = await client.session.list(create(ListSessionsRequestSchema, { pageSize: limit }));
+  return { schema: SessionListSchema, message };
+}
+
+const SESSION_TABLE: TableShape = {
+  resourceName: "sessions",
+  headers: ["SESSION ID", "AGENT", "SUBJECT", "CREATED"],
+  row: (json) => [
+    str(obj(json, "metadata"), "id"),
+    dash(str(obj(json, "spec"), "agent_instance_id")),
+    dash(str(obj(json, "spec"), "subject")),
+    dash(str(obj(json, "metadata"), "created_at")),
+  ],
+};
+
+/** Render a session list (json/yaml = full envelope; table = grid). */
+export function renderSessionList(result: ResourceResult, format: OutputFormat): string {
+  return renderListMessage(result.schema, result.message, format, SESSION_TABLE);
+}
+
+function dash(value: string): string {
+  return value === "" ? "-" : value;
+}

package/src/resources/skill.test.ts

@@ -0,0 +1,227 @@
+// 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 { 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 { classify, ExitCode } from "../errors/index.js";
+import {
+  analyzeDryRun,
+  createSkillZip,
+  formatBytes,
+  hasSkillFile,
+  parseSkillMetadata,
+  parseVisibility,
+  pushSkill,
+  shortHash,
+} from "./skill.js";
+
+const SKILL_MD = ["---", "name: my-skill", "description: a test skill", "---", "# My Skill", "", "Body."].join("\n");
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "skill-test-"));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("parseSkillMetadata", () => {
+  it("parses a valid kebab-case name from frontmatter", () => {
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    expect(parseSkillMetadata(dir)).toEqual({ name: "my-skill" });
+  });
+
+  it("rejects a missing name with a usage error", () => {
+    writeFileSync(join(dir, "SKILL.md"), "---\ndescription: no name\n---\n");
+    const err = (() => {
+      try {
+        parseSkillMetadata(dir);
+      } catch (e) {
+        return e;
+      }
+    })();
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+  });
+
+  it("rejects a non-kebab-case name", () => {
+    writeFileSync(join(dir, "SKILL.md"), "---\nname: My_Skill\n---\n");
+    expect(() => parseSkillMetadata(dir)).toThrow(/kebab-case/);
+  });
+
+  it("rejects content without frontmatter", () => {
+    writeFileSync(join(dir, "SKILL.md"), "# No frontmatter here\n");
+    expect(() => parseSkillMetadata(dir)).toThrow(/frontmatter/);
+  });
+
+  it("parses a declared visibility from frontmatter", () => {
+    writeFileSync(join(dir, "SKILL.md"), "---\nname: my-skill\nvisibility: public\n---\n");
+    expect(parseSkillMetadata(dir)).toEqual({
+      name: "my-skill",
+      visibility: ApiResourceVisibility.visibility_public,
+    });
+  });
+
+  it("leaves visibility undefined when not declared", () => {
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    expect(parseSkillMetadata(dir).visibility).toBeUndefined();
+  });
+});
+
+describe("parseVisibility", () => {
+  it("maps the four short forms", () => {
+    expect(parseVisibility("private")).toBe(ApiResourceVisibility.visibility_private);
+    expect(parseVisibility("public")).toBe(ApiResourceVisibility.visibility_public);
+    expect(parseVisibility("org")).toBe(ApiResourceVisibility.visibility_org);
+    expect(parseVisibility("platform")).toBe(ApiResourceVisibility.visibility_platform);
+  });
+
+  it("accepts canonical enum names and is case/whitespace insensitive", () => {
+    expect(parseVisibility(" Visibility_Public ")).toBe(ApiResourceVisibility.visibility_public);
+    expect(parseVisibility("PUBLIC")).toBe(ApiResourceVisibility.visibility_public);
+  });
+
+  it("treats omitted/unspecified as not declared (undefined)", () => {
+    expect(parseVisibility(undefined)).toBeUndefined();
+    expect(parseVisibility(null)).toBeUndefined();
+    expect(parseVisibility("")).toBeUndefined();
+    expect(parseVisibility("unspecified")).toBeUndefined();
+  });
+
+  it("throws on an unknown value", () => {
+    expect(() => parseVisibility("everyone")).toThrow(/invalid 'visibility'/);
+  });
+
+  it("throws on a non-string value", () => {
+    expect(() => parseVisibility(42)).toThrow(/expected a string/);
+  });
+});
+
+// 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 skillMessage = { metadata: { ...pushMeta } };
+  const client = {
+    skill: {
+      async push() {
+        calls.push++;
+        return skillMessage;
+      },
+      async updateVisibility(input: { resourceId: string; visibility: ApiResourceVisibility }) {
+        calls.updateVisibility.push({ resourceId: input.resourceId, visibility: input.visibility });
+        return { metadata: { ...pushMeta, visibility: input.visibility } };
+      },
+    },
+  } as unknown as Stigmer;
+  return { client, calls };
+}
+
+const NO_IGNORE = { respectGitignore: true, extraIgnore: [], extraInclude: [] };
+
+describe("pushSkill visibility propagation", () => {
+  it("issues an UpdateVisibility RPC when the SKILL.md declares a non-matching visibility", async () => {
+    writeFileSync(join(dir, "SKILL.md"), "---\nname: my-skill\nvisibility: public\n---\n");
+    const { client, calls } = fakeClient({ id: "skill-123", visibility: ApiResourceVisibility.visibility_private });
+
+    const result = await pushSkill(client, dir, "stigmer", "latest", "", NO_IGNORE);
+
+    expect(calls.push).toBe(1);
+    expect(calls.updateVisibility).toEqual([
+      { resourceId: "skill-123", visibility: ApiResourceVisibility.visibility_public },
+    ]);
+    expect(result.visibility).toBe(ApiResourceVisibility.visibility_public);
+  });
+
+  it("does not touch visibility when the SKILL.md omits it", async () => {
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    const { client, calls } = fakeClient({ id: "skill-123", visibility: ApiResourceVisibility.visibility_private });
+
+    await pushSkill(client, dir, "stigmer", "latest", "", NO_IGNORE);
+
+    expect(calls.updateVisibility).toHaveLength(0);
+  });
+
+  it("skips the RPC when the server already matches the declared visibility", async () => {
+    writeFileSync(join(dir, "SKILL.md"), "---\nname: my-skill\nvisibility: public\n---\n");
+    const { client, calls } = fakeClient({ id: "skill-123", visibility: ApiResourceVisibility.visibility_public });
+
+    await pushSkill(client, dir, "stigmer", "latest", "", NO_IGNORE);
+
+    expect(calls.updateVisibility).toHaveLength(0);
+  });
+});
+
+describe("createSkillZip", () => {
+  it("includes survivors and excludes ignored files/dirs", () => {
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    writeFileSync(join(dir, "main.py"), "print('hi')\n");
+    writeFileSync(join(dir, ".env"), "SECRET=1\n"); // default-ignored
+    writeFileSync(join(dir, "notes.log"), "log\n"); // default-ignored (*.log)
+    mkdirSync(join(dir, "node_modules"));
+    writeFileSync(join(dir, "node_modules", "dep.js"), "x\n"); // dir skipped
+    mkdirSync(join(dir, "src"));
+    writeFileSync(join(dir, "src", "util.py"), "u\n");
+
+    const decisions: string[] = [];
+    const { bytes, stats } = createSkillZip(
+      dir,
+      { respectGitignore: true, extraIgnore: [], extraInclude: [] },
+      (line) => decisions.push(line),
+    );
+
+    const entries = Object.keys(unzipSync(bytes)).sort();
+    expect(entries).toEqual(["SKILL.md", "main.py", "src/util.py"]);
+    expect(stats.filesIncluded).toBe(3);
+    expect(stats.dirsSkipped).toBe(1);
+    expect(stats.filesIgnored).toBeGreaterThanOrEqual(2);
+    expect(decisions.some((l) => l.includes("SKIP DIR") && l.includes("node_modules"))).toBe(true);
+  });
+
+  it("force-include overrides a default ignore", () => {
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    writeFileSync(join(dir, ".env"), "SECRET=1\n");
+    const { bytes } = createSkillZip(dir, { respectGitignore: true, extraIgnore: [], extraInclude: [".env"] });
+    expect(Object.keys(unzipSync(bytes))).toContain(".env");
+  });
+});
+
+describe("analyzeDryRun", () => {
+  it("reports counts and pattern sources without producing bytes", () => {
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    writeFileSync(join(dir, "keep.py"), "k\n");
+    writeFileSync(join(dir, ".env"), "S=1\n");
+    const analysis = analyzeDryRun(dir, { respectGitignore: true, extraIgnore: [], extraInclude: [] });
+    expect(analysis.stats.filesIncluded).toBe(2);
+    expect(analysis.stats.filesIgnored).toBeGreaterThanOrEqual(1);
+    expect(analysis.patternSources.some((s) => s.startsWith("defaults"))).toBe(true);
+    expect(analysis.sampleIncluded).toContain("keep.py");
+  });
+});
+
+describe("hasSkillFile", () => {
+  it("detects SKILL.md presence", () => {
+    expect(hasSkillFile(dir)).toBe(false);
+    writeFileSync(join(dir, "SKILL.md"), SKILL_MD);
+    expect(hasSkillFile(dir)).toBe(true);
+  });
+});
+
+describe("formatBytes / shortHash", () => {
+  it("formats byte sizes 1024-based", () => {
+    expect(formatBytes(512)).toBe("512 B");
+    expect(formatBytes(1024)).toBe("1.0 KB");
+    expect(formatBytes(1536)).toBe("1.5 KB");
+    expect(formatBytes(1024 * 1024)).toBe("1.0 MB");
+    expect(formatBytes(1024 * 1024 * 1024)).toBe("1.0 GB");
+  });
+
+  it("truncates hashes for display", () => {
+    expect(shortHash("")).toBe("sha256:(none)");
+    expect(shortHash("abcdef1234567890")).toBe("sha256:abcdef123456");
+    expect(shortHash("abc")).toBe("sha256:abc");
+  });
+});