@gmickel/gno 0.3.0

package/src/cli/commands/shared.ts

@@ -0,0 +1,156 @@
+/**
+ * Shared CLI command utilities.
+ * Common initialization and formatting helpers.
+ *
+ * @module src/cli/commands/shared
+ */
+
+import { getIndexDbPath } from '../../app/constants';
+import { getConfigPaths, isInitialized, loadConfig } from '../../config';
+import type { Collection, Config } from '../../config/types';
+import type { SyncResult } from '../../ingestion';
+import { SqliteAdapter } from '../../store/sqlite/adapter';
+
+/**
+ * Result of CLI store initialization.
+ */
+export type InitStoreResult =
+  | {
+      ok: true;
+      store: SqliteAdapter;
+      config: Config;
+      collections: Collection[];
+      /** Actual config path used (for status reporting) */
+      actualConfigPath: string;
+    }
+  | { ok: false; error: string };
+
+/**
+ * Options for store initialization.
+ */
+export interface InitStoreOptions {
+  /** Override config path */
+  configPath?: string;
+  /** Index name (defaults to 'default') */
+  indexName?: string;
+  /** Filter to single collection by name */
+  collection?: string;
+}
+
+/**
+ * Initialize store for CLI commands.
+ * Handles: isInitialized check, loadConfig, DB open, syncCollections, syncContexts.
+ *
+ * Caller is responsible for calling store.close() when done.
+ */
+export async function initStore(
+  options: InitStoreOptions = {}
+): Promise<InitStoreResult> {
+  // Check if initialized
+  const initialized = await isInitialized(options.configPath);
+  if (!initialized) {
+    return { ok: false, error: 'GNO not initialized. Run: gno init' };
+  }
+
+  // Load config
+  const configResult = await loadConfig(options.configPath);
+  if (!configResult.ok) {
+    return { ok: false, error: configResult.error.message };
+  }
+  const config = configResult.value;
+
+  // Filter to single collection if specified
+  let collections = config.collections;
+  if (options.collection) {
+    collections = collections.filter((c) => c.name === options.collection);
+    if (collections.length === 0) {
+      return {
+        ok: false,
+        error: `Collection not found: ${options.collection}`,
+      };
+    }
+  }
+
+  if (collections.length === 0) {
+    return {
+      ok: false,
+      error: 'No collections configured. Run: gno collection add <path>',
+    };
+  }
+
+  // Ensure data directory exists (may have been deleted by reset)
+  const { ensureDirectories } = await import('../../config');
+  await ensureDirectories();
+
+  // Open database (honor indexName option)
+  const store = new SqliteAdapter();
+  const dbPath = getIndexDbPath(options.indexName);
+  const paths = getConfigPaths();
+
+  // Actual config path used (options.configPath overrides default)
+  const actualConfigPath = options.configPath ?? paths.configFile;
+
+  // Set configPath for status output
+  store.setConfigPath(actualConfigPath);
+
+  const openResult = await store.open(dbPath, config.ftsTokenizer);
+  if (!openResult.ok) {
+    return { ok: false, error: openResult.error.message };
+  }
+
+  // Sync collections from config to DB
+  const syncCollResult = await store.syncCollections(config.collections);
+  if (!syncCollResult.ok) {
+    await store.close();
+    return { ok: false, error: syncCollResult.error.message };
+  }
+
+  // Sync contexts from config to DB
+  const syncCtxResult = await store.syncContexts(config.contexts ?? []);
+  if (!syncCtxResult.ok) {
+    await store.close();
+    return { ok: false, error: syncCtxResult.error.message };
+  }
+
+  return { ok: true, store, config, collections, actualConfigPath };
+}
+
+/**
+ * Format sync result lines (shared between update and index commands).
+ */
+export function formatSyncResultLines(
+  syncResult: SyncResult,
+  options: { verbose?: boolean }
+): string[] {
+  const lines: string[] = [];
+
+  for (const c of syncResult.collections) {
+    lines.push(`${c.collection}:`);
+    lines.push(
+      `  ${c.filesAdded} added, ${c.filesUpdated} updated, ${c.filesUnchanged} unchanged`
+    );
+    if (c.filesErrored > 0) {
+      lines.push(`  ${c.filesErrored} errors`);
+    }
+    if (c.filesMarkedInactive > 0) {
+      lines.push(`  ${c.filesMarkedInactive} marked inactive`);
+    }
+
+    if (options.verbose && c.errors.length > 0) {
+      for (const err of c.errors) {
+        lines.push(`    [${err.code}] ${err.relPath}: ${err.message}`);
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push(
+    `Total: ${syncResult.totalFilesAdded} added, ${syncResult.totalFilesUpdated} updated` +
+      (syncResult.totalFilesErrored > 0
+        ? `, ${syncResult.totalFilesErrored} errors`
+        : '')
+  );
+  lines.push(`Duration: ${syncResult.totalDurationMs}ms`);
+
+  return lines;
+}

package/src/cli/commands/skill/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Skill command exports.
+ *
+ * @module src/cli/commands/skill
+ */
+
+export { type InstallOptions, installSkill } from './install.js';
+export {
+  resolveAllPaths,
+  resolveSkillPaths,
+  type SkillPathOptions,
+  type SkillPaths,
+  type SkillScope,
+  type SkillTarget,
+  validatePathForDeletion,
+} from './paths.js';
+export { type PathsOptions, showPaths } from './paths-cmd.js';
+export { type ShowOptions, showSkill } from './show.js';
+export { type UninstallOptions, uninstallSkill } from './uninstall.js';

package/src/cli/commands/skill/install.ts

@@ -0,0 +1,197 @@
+/**
+ * Install GNO agent skill to Claude Code or Codex.
+ * Atomic install via temp directory + rename.
+ *
+ * @module src/cli/commands/skill/install
+ */
+
+import { mkdir, readdir, rename, rm, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CliError } from '../../errors.js';
+import { getGlobals } from '../../program.js';
+import {
+  resolveSkillPaths,
+  type SkillScope,
+  type SkillTarget,
+  validatePathForDeletion,
+} from './paths.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Source Path Resolution
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get path to skill source files.
+ * Works in both dev (src/) and after build (dist/).
+ */
+function getSkillSourceDir(): string {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  // From src/cli/commands/skill/ -> assets/skill/
+  // Or from dist/cli/commands/skill/ -> assets/skill/
+  return join(__dirname, '../../../../assets/skill');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Install Command
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface InstallOptions {
+  scope?: SkillScope;
+  target?: SkillTarget | 'all';
+  force?: boolean;
+  /** Override for testing */
+  cwd?: string;
+  /** Override for testing */
+  homeDir?: string;
+  /** JSON output (defaults to globals.json) */
+  json?: boolean;
+  /** Non-interactive mode (defaults to globals.yes) */
+  yes?: boolean;
+  /** Quiet mode (defaults to globals.quiet) */
+  quiet?: boolean;
+}
+
+interface InstallResult {
+  target: SkillTarget;
+  scope: SkillScope;
+  path: string;
+}
+
+/**
+ * Install skill to a single target.
+ */
+async function installToTarget(
+  scope: SkillScope,
+  target: SkillTarget,
+  force: boolean,
+  overrides?: { cwd?: string; homeDir?: string }
+): Promise<InstallResult> {
+  const sourceDir = getSkillSourceDir();
+  const paths = resolveSkillPaths({ scope, target, ...overrides });
+
+  // Check if already exists (directory or SKILL.md)
+  const skillMdExists = await Bun.file(join(paths.gnoDir, 'SKILL.md')).exists();
+  let dirExists = false;
+  try {
+    const dirStat = await stat(paths.gnoDir);
+    dirExists = dirStat.isDirectory();
+  } catch {
+    // Directory doesn't exist
+  }
+  const destExists = skillMdExists || dirExists;
+
+  if (destExists && !force) {
+    throw new CliError(
+      'VALIDATION',
+      `Skill already installed at ${paths.gnoDir}. Use --force to overwrite.`
+    );
+  }
+
+  // Read source files
+  const sourceFiles = await readdir(sourceDir);
+  if (sourceFiles.length === 0) {
+    throw new CliError('RUNTIME', `No skill files found in ${sourceDir}`);
+  }
+
+  // Create temp directory with unique name to avoid collisions
+  const randomSuffix = Math.random().toString(36).slice(2, 10);
+  const tmpName = `.gno-skill.tmp.${Date.now()}-${process.pid}-${randomSuffix}`;
+  const tmpDir = join(paths.skillsDir, tmpName);
+
+  try {
+    // Ensure skills directory exists
+    await mkdir(paths.skillsDir, { recursive: true });
+
+    // Create temp directory
+    await mkdir(tmpDir, { recursive: true });
+
+    // Copy all files to temp (binary-safe)
+    for (const file of sourceFiles) {
+      const content = await Bun.file(join(sourceDir, file)).arrayBuffer();
+      await Bun.write(join(tmpDir, file), content);
+    }
+
+    // Remove existing if present (with safety check)
+    if (destExists) {
+      const validationError = validatePathForDeletion(paths.gnoDir, paths.base);
+      if (validationError) {
+        throw new CliError(
+          'RUNTIME',
+          `Safety check failed for ${paths.gnoDir}: ${validationError}`
+        );
+      }
+      await rm(paths.gnoDir, { recursive: true, force: true });
+    }
+
+    // Atomic rename
+    await rename(tmpDir, paths.gnoDir);
+
+    return { target, scope, path: paths.gnoDir };
+  } catch (err) {
+    // Best-effort cleanup
+    try {
+      await rm(tmpDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+
+    if (err instanceof CliError) {
+      throw err;
+    }
+
+    throw new CliError(
+      'RUNTIME',
+      `Failed to install skill: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+/**
+ * Get globals with fallback for testing.
+ */
+function safeGetGlobals(): { json: boolean; yes: boolean; quiet: boolean } {
+  try {
+    return getGlobals();
+  } catch {
+    return { json: false, yes: false, quiet: false };
+  }
+}
+
+/**
+ * Install GNO skill.
+ */
+export async function installSkill(opts: InstallOptions = {}): Promise<void> {
+  const scope = opts.scope ?? 'project';
+  const target = opts.target ?? 'claude';
+  const force = opts.force ?? false;
+  const globals = safeGetGlobals();
+  const json = opts.json ?? globals.json;
+  const yes = opts.yes ?? globals.yes;
+  const quiet = opts.quiet ?? globals.quiet;
+
+  const targets: SkillTarget[] =
+    target === 'all' ? ['claude', 'codex'] : [target];
+
+  const results: InstallResult[] = [];
+
+  for (const t of targets) {
+    const result = await installToTarget(scope, t, force || yes, {
+      cwd: opts.cwd,
+      homeDir: opts.homeDir,
+    });
+    results.push(result);
+  }
+
+  // Output
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ installed: results }, null, 2)}\n`
+    );
+  } else if (!quiet) {
+    for (const r of results) {
+      process.stdout.write(`Installed GNO skill to ${r.path}\n`);
+    }
+    process.stdout.write('\nRestart your agent to load the skill.\n');
+  }
+}

package/src/cli/commands/skill/paths-cmd.ts

@@ -0,0 +1,81 @@
+/**
+ * Show resolved skill installation paths.
+ * Debugging helper for skill install/uninstall.
+ *
+ * @module src/cli/commands/skill/paths-cmd
+ */
+
+import { join } from 'node:path';
+import { getGlobals } from '../../program.js';
+import { resolveAllPaths, type SkillScope, type SkillTarget } from './paths.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Paths Command
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface PathsOptions {
+  scope?: SkillScope | 'all';
+  target?: SkillTarget | 'all';
+  /** Override for testing */
+  cwd?: string;
+  /** Override for testing */
+  homeDir?: string;
+  /** JSON output (defaults to globals.json) */
+  json?: boolean;
+}
+
+interface PathInfo {
+  target: SkillTarget;
+  scope: SkillScope;
+  path: string;
+  exists: boolean;
+}
+
+/**
+ * Get globals with fallback for testing.
+ */
+function safeGetGlobals(): { json: boolean } {
+  try {
+    return getGlobals();
+  } catch {
+    return { json: false };
+  }
+}
+
+/**
+ * Show resolved skill paths.
+ */
+export async function showPaths(opts: PathsOptions = {}): Promise<void> {
+  const scope = opts.scope ?? 'all';
+  const target = opts.target ?? 'all';
+  const globals = safeGetGlobals();
+  const json = opts.json ?? globals.json;
+
+  const resolved = resolveAllPaths(scope, target, {
+    cwd: opts.cwd,
+    homeDir: opts.homeDir,
+  });
+
+  const results: PathInfo[] = [];
+
+  for (const r of resolved) {
+    const skillMdPath = join(r.paths.gnoDir, 'SKILL.md');
+    const exists = await Bun.file(skillMdPath).exists();
+    results.push({
+      target: r.target,
+      scope: r.scope,
+      path: r.paths.gnoDir,
+      exists,
+    });
+  }
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ paths: results }, null, 2)}\n`);
+  } else {
+    process.stdout.write('GNO Skill Paths:\n\n');
+    for (const r of results) {
+      const status = r.exists ? '(installed)' : '(not installed)';
+      process.stdout.write(`  ${r.target}/${r.scope}: ${r.path} ${status}\n`);
+    }
+  }
+}

package/src/cli/commands/skill/paths.ts

@@ -0,0 +1,191 @@
+/**
+ * Path resolution for skill installation.
+ * Supports Claude Code and Codex targets with project/user scopes.
+ *
+ * @module src/cli/commands/skill/paths
+ */
+
+import { homedir } from 'node:os';
+import { isAbsolute, join, normalize, relative, sep } from 'node:path';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Environment Variables
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Override home dir for user scope (testing) */
+export const ENV_SKILLS_HOME_OVERRIDE = 'GNO_SKILLS_HOME_OVERRIDE';
+
+/** Override Claude skills directory */
+export const ENV_CLAUDE_SKILLS_DIR = 'CLAUDE_SKILLS_DIR';
+
+/** Override Codex skills directory */
+export const ENV_CODEX_SKILLS_DIR = 'CODEX_SKILLS_DIR';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type SkillScope = 'project' | 'user';
+export type SkillTarget = 'claude' | 'codex';
+
+export interface SkillPathOptions {
+  scope: SkillScope;
+  target: SkillTarget;
+  /** Override cwd for project scope (testing) */
+  cwd?: string;
+  /** Override home dir for user scope (testing) */
+  homeDir?: string;
+}
+
+export interface SkillPaths {
+  /** Base directory (e.g., ~/.claude or ./.claude) */
+  base: string;
+  /** Skills directory (e.g., ~/.claude/skills) */
+  skillsDir: string;
+  /** GNO skill directory (e.g., ~/.claude/skills/gno) */
+  gnoDir: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Skill name for the gno skill directory */
+export const SKILL_NAME = 'gno';
+
+/** Directory name for skills within agent config */
+const SKILLS_SUBDIR = 'skills';
+
+/** Agent config directory names */
+const AGENT_DIRS: Record<SkillTarget, string> = {
+  claude: '.claude',
+  codex: '.codex',
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Path Resolution
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve skill installation paths for a given scope and target.
+ */
+export function resolveSkillPaths(opts: SkillPathOptions): SkillPaths {
+  const { scope, target, cwd, homeDir } = opts;
+
+  // Check for env overrides first
+  const envOverride =
+    target === 'claude'
+      ? process.env[ENV_CLAUDE_SKILLS_DIR]
+      : process.env[ENV_CODEX_SKILLS_DIR];
+
+  if (envOverride) {
+    // Require absolute path for security
+    if (!isAbsolute(envOverride)) {
+      throw new Error(
+        `${target === 'claude' ? ENV_CLAUDE_SKILLS_DIR : ENV_CODEX_SKILLS_DIR} must be an absolute path`
+      );
+    }
+    const skillsDir = normalize(envOverride);
+    return {
+      base: join(skillsDir, '..'),
+      skillsDir,
+      gnoDir: join(skillsDir, SKILL_NAME),
+    };
+  }
+
+  // Resolve base directory
+  const agentDir = AGENT_DIRS[target];
+  let base: string;
+
+  if (scope === 'user') {
+    const home = homeDir ?? process.env[ENV_SKILLS_HOME_OVERRIDE] ?? homedir();
+    base = join(home, agentDir);
+  } else {
+    const projectRoot = cwd ?? process.cwd();
+    base = join(projectRoot, agentDir);
+  }
+
+  const skillsDir = join(base, SKILLS_SUBDIR);
+  const gnoDir = join(skillsDir, SKILL_NAME);
+
+  return { base, skillsDir, gnoDir };
+}
+
+/**
+ * Resolve paths for all targets given scope options.
+ */
+export function resolveAllPaths(
+  scope: SkillScope | 'all',
+  target: SkillTarget | 'all',
+  overrides?: { cwd?: string; homeDir?: string }
+): Array<{ scope: SkillScope; target: SkillTarget; paths: SkillPaths }> {
+  const scopes: SkillScope[] = scope === 'all' ? ['project', 'user'] : [scope];
+  const targets: SkillTarget[] =
+    target === 'all' ? ['claude', 'codex'] : [target];
+
+  const results: Array<{
+    scope: SkillScope;
+    target: SkillTarget;
+    paths: SkillPaths;
+  }> = [];
+
+  for (const s of scopes) {
+    for (const t of targets) {
+      results.push({
+        scope: s,
+        target: t,
+        paths: resolveSkillPaths({ scope: s, target: t, ...overrides }),
+      });
+    }
+  }
+
+  return results;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Safety Validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Expected path suffix for gno skill directory.
+ * Platform-aware (handles Windows backslash).
+ */
+function getExpectedSuffix(): string {
+  return `${sep}${SKILLS_SUBDIR}${sep}${SKILL_NAME}`;
+}
+
+/**
+ * Validate that a path is safe to delete.
+ * Returns null if safe, or error message if unsafe.
+ */
+export function validatePathForDeletion(
+  destDir: string,
+  base: string
+): string | null {
+  const normalized = normalize(destDir);
+  const normalizedBase = normalize(base);
+  const expectedSuffix = getExpectedSuffix();
+
+  // Must end with /skills/gno (or \skills\gno on Windows)
+  if (!normalized.endsWith(expectedSuffix)) {
+    return `Path does not end with expected suffix (${expectedSuffix})`;
+  }
+
+  // Minimum length sanity check
+  if (normalized.length < 20) {
+    return 'Path is suspiciously short';
+  }
+
+  // Must not equal base
+  if (normalized === normalizedBase) {
+    return 'Path equals base directory';
+  }
+
+  // Must be strictly inside expected base (proper containment check)
+  const rel = relative(normalizedBase, normalized);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    return 'Path is not inside expected base directory';
+  }
+
+  return null;
+}