@stigmer/cli 3.0.8

package/src/resources/skill.ts

@@ -0,0 +1,451 @@
+// `push skill`: package a skill directory into a ZIP artifact and upload it.
+//
+// The directory must contain a SKILL.md with YAML frontmatter naming the skill.
+// Files are filtered through the gitignore-compatible ignore engine, zipped with
+// fflate, and uploaded inline via the Skill push RPC. Git provenance is
+// auto-detected (local) or recorded from the clone (remote --git-url).
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { PushSkillRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { GitProvenanceSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/status_pb";
+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 { 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";
+const SKILL_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+export interface IgnoreOptions {
+  readonly respectGitignore: boolean;
+  readonly extraIgnore: readonly string[];
+  readonly extraInclude: readonly string[];
+}
+
+export interface ZipStats {
+  filesIncluded: number;
+  filesIgnored: number;
+  dirsSkipped: number;
+  totalSize: number;
+}
+
+export interface PushResult {
+  readonly id: string;
+  readonly skillName: string;
+  readonly slug: string;
+  readonly versionHash: string;
+  readonly tag: string;
+  readonly message: string;
+  readonly artifactSize: number;
+  readonly isNewResource: boolean;
+  readonly versionChanged: boolean;
+  /**
+   * The visibility the SKILL.md declared and that was applied after push, if
+   * any. `undefined` means the skill left visibility unspecified and the
+   * server-side value was left untouched (push never silently downgrades).
+   */
+  readonly visibility?: ApiResourceVisibility;
+}
+
+export interface DryRunAnalysis {
+  readonly stats: ZipStats;
+  readonly patternSources: readonly string[];
+  readonly sampleIgnored: readonly string[];
+  readonly sampleIncluded: readonly string[];
+}
+
+/** A callback for --verbose ignore-decision lines (INCLUDE/IGNORE/SKIP DIR). */
+export type DecisionSink = (line: string) => void;
+
+function safeReaddir(dir: string) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+}
+
+export function hasSkillFile(dir: string): boolean {
+  try {
+    return statSync(join(dir, SKILL_FILE)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+interface SkillMetadata {
+  readonly name: string;
+  /**
+   * Declared access level, parsed from the optional `visibility:` frontmatter
+   * key. `undefined` when omitted — the skill keeps whatever the server already
+   * has (default PRIVATE for new skills). This is the declarative replacement
+   * for the Go CLI's `--public-skills` flag.
+   */
+  readonly visibility?: ApiResourceVisibility;
+}
+
+/** Parse SKILL.md YAML frontmatter and validate the skill name (kebab-case). */
+export function parseSkillMetadata(dir: string): SkillMetadata {
+  let content: string;
+  try {
+    content = readFileSync(join(dir, SKILL_FILE), "utf8");
+  } catch (err) {
+    throw new Error(`failed to read ${SKILL_FILE}: ${(err as Error).message}`);
+  }
+
+  const frontmatter = extractFrontmatter(content);
+  const parsed = (parseYaml(frontmatter) ?? {}) as Record<string, unknown>;
+  const name = typeof parsed.name === "string" ? parsed.name : "";
+
+  if (name === "") {
+    throw new UsageError(
+      `${SKILL_FILE} is missing required 'name' field in YAML frontmatter\n\n` +
+        "Expected format:\n---\nname: my-skill-name\n---\n\n" +
+        "The name must be kebab-case (lowercase letters, numbers, and hyphens)",
+    );
+  }
+  if (!SKILL_NAME_RE.test(name)) {
+    throw new UsageError(
+      `invalid skill name '${name}' in ${SKILL_FILE}\n\n` +
+        "Skill names must be kebab-case (a-z, 0-9, hyphens).\n" +
+        "Examples: 'calculator', 'web-scraper', 'math-utils'",
+    );
+  }
+  return { name, visibility: parseVisibility(parsed.visibility, SKILL_FILE) };
+}
+
+// Friendly frontmatter spellings → proto enum. Both the short form (`public`)
+// and the canonical enum name (`visibility_public`) are accepted so authors can
+// copy either from docs or from generated YAML. `unspecified`/empty is treated
+// as "not declared" (returns undefined) so we never emit a no-op update.
+const VISIBILITY_ALIASES: ReadonlyMap<string, ApiResourceVisibility> = new Map([
+  ["private", ApiResourceVisibility.visibility_private],
+  ["visibility_private", ApiResourceVisibility.visibility_private],
+  ["public", ApiResourceVisibility.visibility_public],
+  ["visibility_public", ApiResourceVisibility.visibility_public],
+  ["org", ApiResourceVisibility.visibility_org],
+  ["visibility_org", ApiResourceVisibility.visibility_org],
+  ["platform", ApiResourceVisibility.visibility_platform],
+  ["visibility_platform", ApiResourceVisibility.visibility_platform],
+]);
+
+/**
+ * Map an optional `visibility` frontmatter value to the proto enum. Returns
+ * undefined when omitted or explicitly unspecified; throws on an unknown value
+ * (a typo should fail loudly rather than silently leave a skill private).
+ */
+export function parseVisibility(value: unknown, source = SKILL_FILE): ApiResourceVisibility | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") {
+    throw new UsageError(`invalid 'visibility' in ${source}: expected a string, got ${typeof value}`);
+  }
+  const key = value.trim().toLowerCase();
+  if (key === "" || key === "unspecified" || key === "api_resource_visibility_unspecified") return undefined;
+  const mapped = VISIBILITY_ALIASES.get(key);
+  if (mapped === undefined) {
+    throw new UsageError(
+      `invalid 'visibility' value '${value}' in ${source}\n\n` +
+        "Valid values: private, public, org, platform.",
+    );
+  }
+  return mapped;
+}
+
+function extractFrontmatter(content: string): string {
+  const lines = content.split(/\r?\n/);
+  if (lines.length === 0 || lines[0].trim() !== "---") {
+    throw new UsageError(`${SKILL_FILE} must start with YAML frontmatter (---)`);
+  }
+  const collected: string[] = [];
+  let closed = false;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      closed = true;
+      break;
+    }
+    collected.push(lines[i]);
+  }
+  if (!closed) throw new UsageError(`${SKILL_FILE} frontmatter is not closed (missing closing ---)`);
+  if (collected.length === 0) throw new UsageError(`${SKILL_FILE} has empty frontmatter`);
+  return collected.join("\n");
+}
+
+/** Walk `dir`, filter through the ignore matcher, and zip the survivors. */
+export function createSkillZip(
+  dir: string,
+  options: IgnoreOptions,
+  onDecision?: DecisionSink,
+): { bytes: Uint8Array; stats: ZipStats } {
+  const matcher = createMatcher({
+    rootDir: dir,
+    respectGitignore: options.respectGitignore,
+    includeDefaults: true,
+    extraIgnore: options.extraIgnore,
+    extraInclude: options.extraInclude,
+  });
+
+  const stats: ZipStats = { filesIncluded: 0, filesIgnored: 0, dirsSkipped: 0, totalSize: 0 };
+  const files: Record<string, Uint8Array> = {};
+
+  const walk = (currentDir: string, prefix: string): void => {
+    const entries = readdirSync(currentDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const relPath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      const full = join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        const result = matcher.matchWithReason(relPath, true);
+        if (result.ignored) {
+          stats.dirsSkipped++;
+          onDecision?.(`  SKIP DIR  ${relPath}/ (${REASON_TEXT[result.reason as Reason]})`);
+          continue;
+        }
+        walk(full, relPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+
+      const result = matcher.matchWithReason(relPath, false);
+      if (result.ignored) {
+        stats.filesIgnored++;
+        onDecision?.(`  IGNORE    ${relPath} (${REASON_TEXT[result.reason as Reason]})`);
+        continue;
+      }
+      onDecision?.(`  INCLUDE   ${relPath}`);
+      const data = readFileSync(full);
+      files[relPath] = new Uint8Array(data);
+      stats.filesIncluded++;
+      stats.totalSize += data.length;
+    }
+  };
+  walk(dir, "");
+
+  const bytes = zipSync(files, { level: 6 });
+  return { bytes, stats };
+}
+
+/** Dry-run: report what would be included/ignored without zipping. */
+export function analyzeDryRun(dir: string, options: IgnoreOptions): DryRunAnalysis {
+  const matcher = createMatcher({
+    rootDir: dir,
+    respectGitignore: options.respectGitignore,
+    includeDefaults: true,
+    extraIgnore: options.extraIgnore,
+    extraInclude: options.extraInclude,
+  });
+
+  const stats: ZipStats = { filesIncluded: 0, filesIgnored: 0, dirsSkipped: 0, totalSize: 0 };
+  const sampleIgnored: string[] = [];
+  const sampleIncluded: string[] = [];
+
+  const walk = (currentDir: string, prefix: string): void => {
+    const entries = safeReaddir(currentDir);
+    if (entries === undefined) return; // Skip unreadable directories gracefully (dry-run is best-effort).
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const relPath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      const full = join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        const result = matcher.matchWithReason(relPath, true);
+        if (result.ignored) {
+          stats.dirsSkipped++;
+          if (sampleIgnored.length < 10) sampleIgnored.push(`${relPath}/ (${REASON_TEXT[result.reason as Reason]})`);
+          continue;
+        }
+        walk(full, relPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+
+      const result = matcher.matchWithReason(relPath, false);
+      if (result.ignored) {
+        stats.filesIgnored++;
+        if (sampleIgnored.length < 10) sampleIgnored.push(`${relPath} (${REASON_TEXT[result.reason as Reason]})`);
+      } else {
+        stats.filesIncluded++;
+        try {
+          stats.totalSize += statSync(full).size;
+        } catch {
+          // size unknown; ignore
+        }
+        if (sampleIncluded.length < 10) sampleIncluded.push(relPath);
+      }
+    }
+  };
+  walk(dir, "");
+
+  const sourceCounts = new Map<string, number>();
+  for (const p of matcher.patterns()) {
+    const end = p.indexOf("]");
+    if (p.startsWith("[") && end > 0) {
+      const source = p.slice(1, end);
+      sourceCounts.set(source, (sourceCounts.get(source) ?? 0) + 1);
+    }
+  }
+  const patternSources = [...sourceCounts.entries()].map(([source, count]) => `${source} (${count} patterns)`);
+
+  return { stats, patternSources, sampleIgnored, sampleIncluded };
+}
+
+/** Push a skill from a local directory. Git provenance is auto-detected. */
+export async function pushSkill(
+  client: Stigmer,
+  dir: string,
+  org: string,
+  tag: string,
+  message: string,
+  options: IgnoreOptions,
+  onDecision?: DecisionSink,
+): Promise<PushResult> {
+  if (!hasSkillFile(dir)) {
+    throw new UsageError(
+      `${SKILL_FILE} not found in ${dir}\n\nA skill directory must contain a ${SKILL_FILE} file defining the skill interface`,
+    );
+  }
+  const { name, visibility } = parseSkillMetadata(dir);
+  const { bytes, stats } = createSkillZip(dir, options, onDecision);
+
+  const provenance = collectLocalGitProvenance(dir);
+  const request = create(PushSkillRequestSchema, {
+    org,
+    artifact: bytes,
+    tag: tag === "" ? "latest" : tag,
+    message,
+    gitProvenance: provenance,
+  });
+  const response = await client.skill.push(request);
+  const applied = await applyDeclaredVisibility(client, response, visibility);
+  return toResult(applied, name, message, stats.totalSize, visibility);
+}
+
+export interface RemotePushParams {
+  readonly gitUrl: string;
+  readonly gitRef: string;
+  readonly subdir: string;
+  readonly org: string;
+  readonly tag: string;
+  readonly message: string;
+  readonly options: IgnoreOptions;
+}
+
+/** Push a skill from a directory cloned from a remote git repo (--git-url). */
+export async function pushSkillFromClone(
+  client: Stigmer,
+  skillDir: string,
+  params: RemotePushParams,
+  onDecision?: DecisionSink,
+): Promise<PushResult> {
+  if (!hasSkillFile(skillDir)) {
+    throw new UsageError(`${SKILL_FILE} not found in ${skillDir}\n\nThe skill directory must contain a ${SKILL_FILE} file`);
+  }
+  const { name, visibility } = parseSkillMetadata(skillDir);
+  const { bytes, stats } = createSkillZip(skillDir, params.options, onDecision);
+
+  const commit = getGitCommit(skillDir) ?? "";
+  const provenance = create(GitProvenanceSchema, {
+    remoteUrl: params.gitUrl,
+    ref: params.gitRef,
+    commit,
+    subdir: params.subdir,
+  });
+  const request = create(PushSkillRequestSchema, {
+    org: params.org,
+    artifact: bytes,
+    tag: params.tag === "" ? "latest" : params.tag,
+    message: params.message,
+    gitProvenance: provenance,
+  });
+  const response = await client.skill.push(request);
+  const applied = await applyDeclaredVisibility(client, response, visibility);
+  return toResult(applied, name, params.message, stats.totalSize, 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
+ * of the versioned content), so we follow it with a single UpdateVisibility RPC
+ * — the declarative equivalent of the Go CLI's post-push `--public-skills`
+ * sweep. No-ops (undefined visibility, or the server already matching) are
+ * skipped so an unchanged skill costs nothing extra.
+ */
+async function applyDeclaredVisibility(
+  client: Stigmer,
+  pushed: Skill,
+  visibility: ApiResourceVisibility | undefined,
+): Promise<Skill> {
+  if (visibility === undefined) return pushed;
+  const resourceId = pushed.metadata?.id ?? "";
+  if (resourceId === "") return pushed;
+  if (pushed.metadata?.visibility === visibility) return pushed;
+  return client.skill.updateVisibility(create(UpdateVisibilityInputSchema, { resourceId, visibility }));
+}
+
+function collectLocalGitProvenance(dir: string) {
+  const root = getGitRepoRoot(dir);
+  if (root === undefined) return undefined;
+  const remoteUrl = getGitRemoteUrl(dir);
+  if (remoteUrl === undefined) return undefined; // No remote → no meaningful provenance.
+
+  const provenance = create(GitProvenanceSchema, { remoteUrl });
+  const commit = getGitCommit(dir);
+  if (commit !== undefined) provenance.commit = commit;
+  const branch = getGitBranchName(dir);
+  if (branch !== undefined) provenance.ref = branch;
+
+  // Subdir relative to repo root (git returns an absolute toplevel path).
+  const rel = relative(root, resolve(dir));
+  if (rel !== "" && rel !== ".") provenance.subdir = rel;
+  return provenance;
+}
+
+function toResult(
+  response: Skill,
+  skillName: string,
+  message: string,
+  size: number,
+  visibility: ApiResourceVisibility | undefined,
+): PushResult {
+  const version = response.metadata?.version;
+  const isNew = version === undefined ? false : version.previousVersionId === "";
+  const changed =
+    version === undefined ? true : version.previousVersionId === "" ? true : version.id !== version.previousVersionId;
+  return {
+    id: response.metadata?.id ?? "",
+    skillName,
+    slug: response.metadata?.slug ?? "",
+    versionHash: response.status?.versionHash ?? "",
+    tag: response.spec?.tag ?? "",
+    message,
+    artifactSize: size,
+    isNewResource: isNew,
+    versionChanged: changed,
+    visibility,
+  };
+}
+
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB", "PB"] as const;
+
+/** Human-readable byte size (1024-based), matching Go's formatBytes. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  let div = 1024;
+  let exp = 0;
+  for (let n = Math.floor(bytes / 1024); n >= 1024; n = Math.floor(n / 1024)) {
+    div *= 1024;
+    exp++;
+  }
+  return `${(bytes / div).toFixed(1)} ${BYTE_UNITS[exp + 1]}`;
+}
+
+/** Friendly truncated sha256 identifier. */
+export function shortHash(hash: string): string {
+  if (hash === "") return "sha256:(none)";
+  return `sha256:${hash.length > 12 ? hash.slice(0, 12) : hash}`;
+}

package/src/resources/stream/approval-detect.ts

@@ -0,0 +1,118 @@
+// Human-in-the-loop approval detection for the snapshot differ.
+//
+// Ports the dual-detection logic from Go's run_stream_events.go (the
+// pending_approvals scan at :397-415 and the defense-in-depth tool-status scan
+// at :417-448) plus the helpers in run_stream_approval.go. The differ uses these
+// to emit ApprovalNeededEvent exactly once per tool call until a new approval
+// cycle resets the dedup set.
+
+import { create } from "@bufbuild/protobuf";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  type PendingApproval,
+  PendingApprovalSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ApprovalNeededEvent } from "./events.js";
+
+/** A tool call awaiting approval, with sub-agent provenance. Mirrors Go's unpromptedApproval. */
+export interface UnpromptedApproval {
+  readonly toolCall: ToolCall;
+  readonly fromSubAgent: boolean;
+  readonly subAgentName: string;
+}
+
+/** The dedup key for a pending approval (its tool-call ID). Mirrors Go's approvalDedupKey. */
+export function approvalDedupKey(pa: PendingApproval): string {
+  return pa.toolCallId;
+}
+
+/**
+ * True if at least one approval has a non-empty key not yet prompted. When every
+ * entry is degraded or already prompted, the caller falls back to the tool-status
+ * scan. Mirrors Go's hasUsableApproval.
+ */
+export function hasUsableApproval(approvals: readonly PendingApproval[], promptedIds: ReadonlySet<string>): boolean {
+  return approvals.some((pa) => {
+    const key = approvalDedupKey(pa);
+    return key !== "" && !promptedIds.has(key);
+  });
+}
+
+/**
+ * Scan top-level and sub-agent tool calls for any in WAITING_APPROVAL not yet
+ * prompted. This is the defense-in-depth path for snapshots whose
+ * pending_approvals is missing or degraded. Mirrors Go's findAllUnpromptedApprovals.
+ */
+export function findAllUnpromptedApprovals(
+  toolCalls: readonly ToolCall[],
+  subAgents: readonly SubAgentExecution[],
+  promptedIds: ReadonlySet<string>,
+): UnpromptedApproval[] {
+  const result: UnpromptedApproval[] = [];
+
+  for (const tc of toolCalls) {
+    if (isUnpromptedWaiting(tc, promptedIds)) {
+      result.push({ toolCall: tc, fromSubAgent: false, subAgentName: "" });
+    }
+  }
+
+  for (const sa of subAgents) {
+    for (const msg of sa.messages) {
+      for (const tc of msg.toolCalls) {
+        if (isUnpromptedWaiting(tc, promptedIds)) {
+          result.push({ toolCall: tc, fromSubAgent: true, subAgentName: sa.name });
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+function isUnpromptedWaiting(tc: ToolCall, promptedIds: ReadonlySet<string>): boolean {
+  return tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL && tc.id !== "" && !promptedIds.has(tc.id);
+}
+
+/**
+ * Build a synthetic PendingApproval from a tool call, for the tool-status scan
+ * path where the phase-level approval is unavailable. Mirrors Go's
+ * buildPendingApprovalFromToolCall.
+ */
+export function buildPendingApprovalFromToolCall(tc: ToolCall): PendingApproval {
+  return create(PendingApprovalSchema, {
+    toolCallId: tc.id,
+    toolName: tc.name,
+    requestedAt: tc.startedAt,
+    argsPreview: tc.args !== undefined ? JSON.stringify(tc.args) : "",
+  });
+}
+
+/**
+ * Extract the ApprovalNeededEvent payload from a tool call and pending approval,
+ * preferring the richer PendingApproval fields and filling gaps from the tool
+ * call. Mirrors Go's extractApprovalInfo. `dedupKey` is the key already chosen
+ * by the caller (so the cycle-reset bookkeeping stays consistent).
+ */
+export function buildApprovalNeeded(tc: ToolCall | undefined, pa: PendingApproval): ApprovalNeededEvent {
+  let toolCallId = pa.toolCallId;
+  let toolName = pa.toolName;
+  let argsPreview = pa.argsPreview;
+
+  if (tc !== undefined) {
+    if (toolCallId === "") toolCallId = tc.id;
+    if (toolName === "") toolName = tc.name;
+    if (argsPreview === "" && tc.args !== undefined) argsPreview = JSON.stringify(tc.args);
+  }
+
+  return {
+    kind: "approvalNeeded",
+    toolCallId,
+    toolName,
+    argsPreview,
+    message: pa.message,
+    fromSubAgent: pa.fromSubAgent,
+    subAgentName: pa.subAgentName,
+  };
+}