@sna-sdk/core 0.0.0

package/bin/sna.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+import { resolve, dirname } from 'path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const entry = resolve(__dirname, '../dist/scripts/sna.js')
+
+const child = spawn(process.execPath, [entry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  shell: false,
+})
+
+child.on('exit', (code) => process.exit(code ?? 0))
+child.on('error', (err) => {
+  console.error('Error:', err.message)
+  process.exit(1)
+})

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,104 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import chalk from "chalk";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const [, , command] = process.argv;
+switch (command) {
+  case "link":
+    cmdLink();
+    break;
+  case "install":
+    cmdInstall();
+    break;
+  default:
+    console.log(`
+${chalk.bold("sna")} \u2014 Skills-Native Application core primitives
+
+${chalk.bold("Usage:")}
+  sna link      Create/update .claude/skills symlinks
+  sna install   Add sna to package.json and link skills
+`);
+}
+function cmdLink() {
+  const cwd = process.cwd();
+  const claudeDir = path.join(cwd, ".claude");
+  const skillsDir = path.join(claudeDir, "skills");
+  if (!fs.existsSync(skillsDir)) {
+    fs.mkdirSync(skillsDir, { recursive: true });
+    console.log(chalk.gray(`  created  .claude/skills/`));
+  }
+  const coreSkillsDir = path.join(PACKAGE_ROOT, "skills");
+  if (!fs.existsSync(coreSkillsDir)) {
+    console.error(chalk.red(`  \u2717  sna skills directory not found: ${coreSkillsDir}`));
+    process.exit(1);
+  }
+  const skills = fs.readdirSync(coreSkillsDir).filter(
+    (f) => fs.statSync(path.join(coreSkillsDir, f)).isDirectory()
+  );
+  let linked = 0;
+  let updated = 0;
+  let skipped = 0;
+  for (const skill of skills) {
+    const linkPath = path.join(skillsDir, skill);
+    const target = path.relative(skillsDir, path.join(coreSkillsDir, skill));
+    let existing = null;
+    try {
+      existing = fs.lstatSync(linkPath);
+    } catch {
+    }
+    if (existing) {
+      if (existing.isSymbolicLink()) {
+        const currentTarget = fs.readlinkSync(linkPath);
+        if (currentTarget === target) {
+          skipped++;
+          continue;
+        }
+        fs.unlinkSync(linkPath);
+        fs.symlinkSync(target, linkPath);
+        console.log(chalk.cyan(`  updated  .claude/skills/${skill}/ \u2192 ${target}`));
+        updated++;
+      } else {
+        console.log(chalk.yellow(`  skipped  .claude/skills/${skill}/  (not a symlink \u2014 won't overwrite)`));
+        skipped++;
+      }
+    } else {
+      fs.symlinkSync(target, linkPath);
+      console.log(chalk.green(`  linked   .claude/skills/${skill}/ \u2192 ${target}`));
+      linked++;
+    }
+  }
+  console.log();
+  if (linked + updated > 0) {
+    console.log(chalk.green(`\u2713  ${linked + updated} skill(s) linked`));
+  } else {
+    console.log(chalk.gray(`\u2713  Skills already up to date`));
+  }
+  if (skipped > 0 && linked + updated > 0) {
+    console.log(chalk.gray(`   (${skipped} unchanged)`));
+  }
+}
+function cmdInstall() {
+  const cwd = process.cwd();
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    console.error(chalk.red("  \u2717  No package.json found in current directory"));
+    process.exit(1);
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  const hasSnaCoreAlready = pkg.dependencies?.["sna"] || pkg.devDependencies?.["sna"];
+  if (!hasSnaCoreAlready) {
+    const snaPkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
+    const version = snaPkg.version ?? "latest";
+    pkg.dependencies = pkg.dependencies ?? {};
+    pkg.dependencies["sna"] = `^${version}`;
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    console.log(chalk.green(`  added    "sna": "^${version}" to dependencies`));
+    console.log(chalk.gray(`  run      pnpm install  to install`));
+  } else {
+    console.log(chalk.gray(`  sna already in package.json`));
+  }
+  console.log();
+  cmdLink();
+}

package/dist/core/providers/claude-code.d.ts

@@ -0,0 +1,9 @@
+import { AgentProvider, SpawnOptions, AgentProcess } from './types.js';
+
+declare class ClaudeCodeProvider implements AgentProvider {
+    readonly name = "claude-code";
+    isAvailable(): Promise<boolean>;
+    spawn(options: SpawnOptions): AgentProcess;
+}
+
+export { ClaudeCodeProvider };

package/dist/core/providers/claude-code.js

@@ -0,0 +1,257 @@
+import { spawn, execSync } from "child_process";
+import { EventEmitter } from "events";
+import fs from "fs";
+import path from "path";
+import { logger } from "../../lib/logger.js";
+const SHELL = process.env.SHELL || "/bin/zsh";
+function resolveClaudePath(cwd) {
+  const cached = path.join(cwd, ".sna/claude-path");
+  if (fs.existsSync(cached)) {
+    const p = fs.readFileSync(cached, "utf8").trim();
+    if (p) {
+      try {
+        execSync(`test -x "${p}"`, { stdio: "pipe" });
+        return p;
+      } catch {
+      }
+    }
+  }
+  for (const p of [
+    "/opt/homebrew/bin/claude",
+    "/usr/local/bin/claude",
+    `${process.env.HOME}/.local/bin/claude`
+  ]) {
+    try {
+      execSync(`test -x "${p}"`, { stdio: "pipe" });
+      return p;
+    } catch {
+    }
+  }
+  try {
+    return execSync(`${SHELL} -l -c "which claude"`, { encoding: "utf8" }).trim();
+  } catch {
+    return "claude";
+  }
+}
+class ClaudeCodeProcess {
+  constructor(proc, options) {
+    this.emitter = new EventEmitter();
+    this._alive = true;
+    this._sessionId = null;
+    this.buffer = "";
+    this.proc = proc;
+    proc.stdout.on("data", (chunk) => {
+      this.buffer += chunk.toString();
+      const lines = this.buffer.split("\n");
+      this.buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        logger.log("stdout", line);
+        try {
+          const msg = JSON.parse(line);
+          if (msg.session_id && !this._sessionId) {
+            this._sessionId = msg.session_id;
+          }
+          const event = this.normalizeEvent(msg);
+          if (event) this.emitter.emit("event", event);
+        } catch {
+        }
+      }
+    });
+    proc.stderr.on("data", () => {
+    });
+    proc.on("exit", (code) => {
+      this._alive = false;
+      if (this.buffer.trim()) {
+        try {
+          const msg = JSON.parse(this.buffer);
+          const event = this.normalizeEvent(msg);
+          if (event) this.emitter.emit("event", event);
+        } catch {
+        }
+      }
+      this.emitter.emit("exit", code);
+      logger.log("agent", `process exited (code=${code})`);
+    });
+    proc.on("error", (err) => {
+      this._alive = false;
+      this.emitter.emit("error", err);
+    });
+    if (options.prompt) {
+      this.send(options.prompt);
+    }
+  }
+  get alive() {
+    return this._alive;
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  /**
+   * Send a user message to the persistent Claude process via stdin.
+   */
+  send(input) {
+    if (!this._alive || !this.proc.stdin.writable) return;
+    const msg = JSON.stringify({
+      type: "user",
+      message: { role: "user", content: input }
+    });
+    logger.log("stdin", msg.slice(0, 200));
+    this.proc.stdin.write(msg + "\n");
+  }
+  kill() {
+    if (this._alive) {
+      this._alive = false;
+      this.proc.kill("SIGTERM");
+    }
+  }
+  on(event, handler) {
+    this.emitter.on(event, handler);
+  }
+  off(event, handler) {
+    this.emitter.off(event, handler);
+  }
+  normalizeEvent(msg) {
+    switch (msg.type) {
+      case "system": {
+        if (msg.subtype === "init") {
+          return {
+            type: "init",
+            message: `Agent ready (${msg.model ?? "unknown"})`,
+            data: { sessionId: msg.session_id, model: msg.model },
+            timestamp: Date.now()
+          };
+        }
+        return null;
+      }
+      case "assistant": {
+        const content = msg.message?.content;
+        if (!Array.isArray(content)) return null;
+        const events = [];
+        for (const block of content) {
+          if (block.type === "thinking") {
+            events.push({
+              type: "thinking",
+              message: block.thinking ?? "",
+              timestamp: Date.now()
+            });
+          } else if (block.type === "tool_use") {
+            events.push({
+              type: "tool_use",
+              message: block.name,
+              data: { toolName: block.name, input: block.input, id: block.id },
+              timestamp: Date.now()
+            });
+          } else if (block.type === "text") {
+            const text = (block.text ?? "").trim();
+            if (text) {
+              events.push({ type: "assistant", message: text, timestamp: Date.now() });
+            }
+          }
+        }
+        if (events.length > 0) {
+          for (let i = 1; i < events.length; i++) {
+            this.emitter.emit("event", events[i]);
+          }
+          return events[0];
+        }
+        return null;
+      }
+      case "user": {
+        const userContent = msg.message?.content;
+        if (!Array.isArray(userContent)) return null;
+        for (const block of userContent) {
+          if (block.type === "tool_result") {
+            return {
+              type: "tool_result",
+              message: typeof block.content === "string" ? block.content.slice(0, 300) : JSON.stringify(block.content).slice(0, 300),
+              data: { toolUseId: block.tool_use_id, isError: block.is_error },
+              timestamp: Date.now()
+            };
+          }
+        }
+        return null;
+      }
+      case "result": {
+        if (msg.subtype === "success") {
+          const mu = msg.modelUsage ?? {};
+          const modelKey = Object.keys(mu)[0] ?? "";
+          const u = mu[modelKey] ?? {};
+          return {
+            type: "complete",
+            message: msg.result ?? "Done",
+            data: {
+              durationMs: msg.duration_ms,
+              costUsd: msg.total_cost_usd,
+              inputTokens: u.inputTokens ?? 0,
+              outputTokens: u.outputTokens ?? 0,
+              cacheReadTokens: u.cacheReadInputTokens ?? 0,
+              cacheWriteTokens: u.cacheCreationInputTokens ?? 0,
+              contextWindow: u.contextWindow ?? 0,
+              maxOutputTokens: u.maxOutputTokens ?? 0,
+              model: modelKey
+            },
+            timestamp: Date.now()
+          };
+        }
+        if (msg.subtype === "error" || msg.is_error) {
+          return {
+            type: "error",
+            message: msg.result ?? msg.error ?? "Unknown error",
+            timestamp: Date.now()
+          };
+        }
+        return null;
+      }
+      case "rate_limit_event":
+        return null;
+      default:
+        logger.log("agent", `unhandled event: ${msg.type}`, JSON.stringify(msg).substring(0, 200));
+        return null;
+    }
+  }
+}
+class ClaudeCodeProvider {
+  constructor() {
+    this.name = "claude-code";
+  }
+  async isAvailable() {
+    try {
+      const p = resolveClaudePath(process.cwd());
+      execSync(`test -x "${p}"`, { stdio: "pipe" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  spawn(options) {
+    const claudePath = resolveClaudePath(options.cwd);
+    const args = [
+      "--output-format",
+      "stream-json",
+      "--input-format",
+      "stream-json",
+      "--verbose"
+    ];
+    if (options.model) {
+      args.push("--model", options.model);
+    }
+    if (options.permissionMode) {
+      args.push("--permission-mode", options.permissionMode);
+    }
+    const cleanEnv = { ...process.env, ...options.env };
+    delete cleanEnv.CLAUDECODE;
+    delete cleanEnv.CLAUDE_CODE_ENTRYPOINT;
+    delete cleanEnv.CLAUDE_CODE_SESSION_ACCESS_TOKEN;
+    const proc = spawn(claudePath, args, {
+      cwd: options.cwd,
+      env: cleanEnv,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    logger.log("agent", `spawned claude-code (pid=${proc.pid})`);
+    return new ClaudeCodeProcess(proc, options);
+  }
+}
+export {
+  ClaudeCodeProvider
+};

package/dist/core/providers/codex.d.ts

@@ -0,0 +1,18 @@
+import { AgentProvider, SpawnOptions, AgentProcess } from './types.js';
+
+/**
+ * Codex provider stub.
+ *
+ * Codex uses JSONL output: `codex exec --json "prompt"`
+ * Event types: thread.started, turn.started, turn.completed,
+ *              turn.failed, item.completed, error
+ *
+ * Not yet implemented — placeholder to validate the provider interface.
+ */
+declare class CodexProvider implements AgentProvider {
+    readonly name = "codex";
+    isAvailable(): Promise<boolean>;
+    spawn(_options: SpawnOptions): AgentProcess;
+}
+
+export { CodexProvider };

package/dist/core/providers/codex.js

@@ -0,0 +1,14 @@
+class CodexProvider {
+  constructor() {
+    this.name = "codex";
+  }
+  async isAvailable() {
+    return false;
+  }
+  spawn(_options) {
+    throw new Error("Codex provider not yet implemented");
+  }
+}
+export {
+  CodexProvider
+};

package/dist/core/providers/index.d.ts

@@ -0,0 +1,14 @@
+import { AgentProvider } from './types.js';
+export { AgentEvent, AgentProcess, SpawnOptions } from './types.js';
+export { ClaudeCodeProvider } from './claude-code.js';
+export { CodexProvider } from './codex.js';
+
+/**
+ * Get a registered provider by name.
+ * @throws if provider not found
+ */
+declare function getProvider(name?: string): AgentProvider;
+/** Register a custom provider. */
+declare function registerProvider(provider: AgentProvider): void;
+
+export { AgentProvider, getProvider, registerProvider };

package/dist/core/providers/index.js

@@ -0,0 +1,22 @@
+import { ClaudeCodeProvider } from "./claude-code.js";
+import { CodexProvider } from "./codex.js";
+import { ClaudeCodeProvider as ClaudeCodeProvider2 } from "./claude-code.js";
+import { CodexProvider as CodexProvider2 } from "./codex.js";
+const providers = {
+  "claude-code": new ClaudeCodeProvider2(),
+  "codex": new CodexProvider2()
+};
+function getProvider(name = "claude-code") {
+  const provider = providers[name];
+  if (!provider) throw new Error(`Unknown agent provider: ${name}`);
+  return provider;
+}
+function registerProvider(provider) {
+  providers[provider.name] = provider;
+}
+export {
+  ClaudeCodeProvider,
+  CodexProvider,
+  getProvider,
+  registerProvider
+};

package/dist/core/providers/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Normalized event type emitted by all agent providers.
+ *
+ * Providers translate their native event format (Claude Code stream-json,
+ * Codex JSONL, etc.) into these common types.
+ */
+interface AgentEvent {
+    type: "init" | "thinking" | "text_delta" | "assistant" | "tool_use" | "tool_result" | "permission_needed" | "milestone" | "error" | "complete";
+    message?: string;
+    data?: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * A running agent process. Wraps a child_process with typed event handlers.
+ */
+interface AgentProcess {
+    /** Send a user message to the agent's stdin. */
+    send(input: string): void;
+    /** Kill the agent process. */
+    kill(): void;
+    /** Whether the process is still running. */
+    readonly alive: boolean;
+    /** Session ID assigned by the provider. */
+    readonly sessionId: string | null;
+    on(event: "event", handler: (e: AgentEvent) => void): void;
+    on(event: "exit", handler: (code: number | null) => void): void;
+    on(event: "error", handler: (err: Error) => void): void;
+    off(event: string, handler: Function): void;
+}
+/**
+ * Options for spawning an agent session.
+ */
+interface SpawnOptions {
+    cwd: string;
+    prompt?: string;
+    model?: string;
+    permissionMode?: "default" | "acceptEdits" | "bypassPermissions" | "plan";
+    env?: Record<string, string>;
+}
+/**
+ * Agent provider interface. Each backend (Claude Code, Codex, etc.)
+ * implements this to provide a unified spawn → events → send API.
+ */
+interface AgentProvider {
+    readonly name: string;
+    /** Check if this provider's CLI is available on the system. */
+    isAvailable(): Promise<boolean>;
+    /** Spawn a new agent session. */
+    spawn(options: SpawnOptions): AgentProcess;
+}
+
+export type { AgentEvent, AgentProcess, AgentProvider, SpawnOptions };

package/dist/db/schema.d.ts

@@ -0,0 +1,13 @@
+import Database from 'better-sqlite3';
+
+declare function getDb(): Database.Database;
+interface SkillEvent {
+    id: number;
+    skill: string;
+    type: "invoked" | "called" | "success" | "failed" | "permission_needed" | "start" | "progress" | "milestone" | "complete" | "error";
+    message: string;
+    data: string | null;
+    created_at: string;
+}
+
+export { type SkillEvent, getDb };

package/dist/db/schema.js

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+import path from "path";
+const require2 = createRequire(path.join(process.cwd(), "node_modules", "_"));
+const BetterSqlite3 = require2("better-sqlite3");
+const DB_PATH = path.join(process.cwd(), "data/sna.db");
+let _db = null;
+function getDb() {
+  if (!_db) {
+    _db = new BetterSqlite3(DB_PATH);
+    _db.pragma("journal_mode = WAL");
+    initSchema(_db);
+  }
+  return _db;
+}
+function migrateSkillEvents(db) {
+  const row = db.prepare(
+    "SELECT sql FROM sqlite_master WHERE type='table' AND name='skill_events'"
+  ).get();
+  if (row?.sql?.includes("CHECK(type IN")) {
+    db.exec("DROP TABLE IF EXISTS skill_events");
+  }
+}
+function initSchema(db) {
+  migrateSkillEvents(db);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS skill_events (
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      skill      TEXT NOT NULL,
+      type       TEXT NOT NULL,
+      message    TEXT NOT NULL,
+      data       TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_skill_events_skill ON skill_events(skill);
+    CREATE INDEX IF NOT EXISTS idx_skill_events_created ON skill_events(created_at);
+  `);
+}
+export {
+  getDb
+};

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { SkillEvent } from './db/schema.js';
+export { AgentEvent, AgentProcess, AgentProvider, SpawnOptions } from './core/providers/types.js';
+export { Session, SessionInfo, SessionManagerOptions } from './server/session-manager.js';
+import 'better-sqlite3';
+
+/**
+ * @sna-sdk/core — Skills-Native Application runtime.
+ *
+ * Server, providers, session management, database, and CLI.
+ * No React dependency.
+ */
+declare const DEFAULT_SNA_PORT = 3099;
+declare const DEFAULT_SNA_URL = "http://localhost:3099";
+
+export { DEFAULT_SNA_PORT, DEFAULT_SNA_URL };

package/dist/index.js

@@ -0,0 +1,6 @@
+const DEFAULT_SNA_PORT = 3099;
+const DEFAULT_SNA_URL = `http://localhost:${DEFAULT_SNA_PORT}`;
+export {
+  DEFAULT_SNA_PORT,
+  DEFAULT_SNA_URL
+};

package/dist/lib/logger.d.ts

@@ -0,0 +1,18 @@
+declare const tags: {
+    readonly sna: string;
+    readonly req: string;
+    readonly agent: string;
+    readonly stdin: string;
+    readonly stdout: string;
+    readonly route: string;
+    readonly err: string;
+};
+type Tag = keyof typeof tags;
+declare function log(tag: Tag, ...args: unknown[]): void;
+declare function err(tag: Tag, ...args: unknown[]): void;
+declare const logger: {
+    log: typeof log;
+    err: typeof err;
+};
+
+export { logger };

package/dist/lib/logger.js

@@ -0,0 +1,50 @@
+import chalk from "chalk";
+import fs from "fs";
+import path from "path";
+const LOG_PATH = path.join(process.cwd(), ".dev.log");
+try {
+  fs.writeFileSync(LOG_PATH, "");
+} catch {
+}
+function tsPlain() {
+  return (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" });
+}
+function tsColored() {
+  return chalk.gray(tsPlain());
+}
+const tags = {
+  sna: chalk.bold.magenta(" SNA "),
+  req: chalk.bold.blue(" REQ "),
+  agent: chalk.bold.cyan(" AGT "),
+  stdin: chalk.bold.green(" IN  "),
+  stdout: chalk.bold.yellow(" OUT "),
+  route: chalk.bold.blue(" API "),
+  err: chalk.bold.red(" ERR ")
+};
+const tagPlain = {
+  sna: " SNA ",
+  req: " REQ ",
+  agent: " AGT ",
+  stdin: " IN  ",
+  stdout: " OUT ",
+  route: " API ",
+  err: " ERR "
+};
+function appendFile(tag, args) {
+  const line = `${tsPlain()} ${tag} ${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}
+`;
+  fs.appendFile(LOG_PATH, line, () => {
+  });
+}
+function log(tag, ...args) {
+  console.log(`${tsColored()} ${tags[tag]}`, ...args);
+  appendFile(tagPlain[tag], args);
+}
+function err(tag, ...args) {
+  console.error(`${tsColored()} ${tags[tag]}`, ...args);
+  appendFile(tagPlain[tag], args);
+}
+const logger = { log, err };
+export {
+  logger
+};