@imagina-build/ias-cli 0.2.2 → 0.3.1

package/src/skill.mjs

@@ -0,0 +1,256 @@
+// The agent skill of IAS: the catalog the server publishes, the copy the CLI carries (skill-files.generated.mjs, written
+// by scripts/sync-skill.mjs from .claude/skills/ias) and the two places a project can get it: an OpenCode catalog in
+// opencode.jsonc and the files themselves in .opencode/skills/ias or .claude/skills/ias. Nothing here uses the network.
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { IasError } from './errors.mjs';
+import { SKILL_FILES } from './skill-files.generated.mjs';
+
+/** The OpenCode V2 catalog the server serves: index.json, ias/SKILL.md and ias/references/*.md. */
+export const SKILL_CATALOG_URL = 'https://ias.imagina.build/skills/';
+
+export const SKILL_NAME = 'ias';
+
+/** Where OpenCode looks for a configuration, in the order ias init takes the first one it finds. */
+export const OPENCODE_CONFIG_FILES = ['opencode.jsonc', 'opencode.json', '.opencode/opencode.jsonc', '.opencode/opencode.json'];
+
+export const AGENTS_FILE = 'AGENTS.md';
+
+/** The section ias init adds to AGENTS.md, once. */
+export const AGENTS_SECTION = [
+  '## IAS',
+  '',
+  'This project uses Imagina Application Services (IAS). Run `ias setup` to see the checklist.',
+  `The agent skill is at ${SKILL_CATALOG_URL} (OpenCode) or install it with \`ias skill install\`.`,
+].join('\n');
+
+/** The line a JSONC configuration needs by hand: it is never rewritten. */
+export const SKILL_CONFIG_LINE = `"skills": ["${SKILL_CATALOG_URL}"]`;
+
+/** The folder of the skill in this repository, when ias runs from a clone (it is absent in an installed package). */
+export const REPOSITORY_SKILL_DIR = fileURLToPath(new URL('../../../.claude/skills/ias/', import.meta.url));
+
+/** The home of `env`, so the tests never touch the real one. */
+export function homeOf(env = process.env) {
+  return env?.HOME || env?.USERPROFILE || homedir();
+}
+
+/**
+ * Where `ias skill install` writes: [{ harness, path }]. The project's OpenCode folder by default, ~/.config/opencode with
+ * --global, and the Claude Code folder as well with --claude (.claude/skills/ias, or ~/.claude/skills/ias with --global).
+ */
+export function skillTargets({ global = false, claude = false, dir = process.cwd(), env = process.env } = {}) {
+  const root = global ? homeOf(env) : dir;
+  const targets = [{ harness: 'opencode', path: join(root, global ? '.config/opencode/skills' : '.opencode/skills', SKILL_NAME) }];
+  if (claude) targets.push({ harness: 'claude', path: join(root, '.claude/skills', SKILL_NAME) });
+  return targets;
+}
+
+/** Whether `a` and `b` are the same folder (the same path, or the same real path when both exist). */
+function samePath(a, b) {
+  const one = resolve(a);
+  const other = resolve(b);
+  if (one === other) return true;
+  try {
+    return realpathSync(one) === realpathSync(other);
+  } catch {
+    return false;
+  }
+}
+
+const sameContents = (file, contents) => existsSync(file) && readFileSync(file, 'utf8') === contents;
+
+/**
+ * Installs the skill from this package (offline) in the target folders. Without `force`, an existing file with other
+ * contents stops it before anything is written, and the files are listed. The repository's .claude/skills/ias is the
+ * source: when a target is that same folder, it is skipped, never rewritten.
+ *
+ * Returns { dry_run, targets, files, written, would_write, skipped, source }.
+ */
+export function installSkill({ global = false, claude = false, force = false, dryRun = false, dir = process.cwd(), env = process.env } = {}, output) {
+  const targets = skillTargets({ global, claude, dir, env });
+  const files = Object.keys(SKILL_FILES);
+  const plan = targets.map((target) => {
+    const source = samePath(target.path, REPOSITORY_SKILL_DIR);
+    const missing = [];
+    const identical = [];
+    const different = [];
+    if (!source) {
+      for (const file of files) {
+        if (!existsSync(join(target.path, file))) missing.push(file);
+        else if (sameContents(join(target.path, file), SKILL_FILES[file])) identical.push(file);
+        else different.push(file);
+      }
+    }
+    return { ...target, source, missing, identical, different };
+  });
+
+  const conflicts = plan.filter((target) => !target.source && target.different.length > 0);
+  if (!force && conflicts.length > 0) {
+    const listed = conflicts.flatMap((target) => target.different.map((file) => join(target.path, file)));
+    throw new IasError(`the skill is already there with other contents (${listed.join(', ')})`, {
+      fix: 'ias skill update replaces it, or ias skill install --force; --dry-run shows the plan without writing',
+    });
+  }
+
+  const written = [];
+  const wouldWrite = [];
+  const skipped = [];
+  for (const target of plan) {
+    if (target.source) {
+      skipped.push(target.path);
+      output?.log(`${output.prefix}: ${target.path} is the source of the skill (.claude/skills/ias): left as it is`);
+      continue;
+    }
+    for (const file of files) {
+      const path = join(target.path, file);
+      const write = target.missing.includes(file) || target.different.includes(file);
+      if (!write) {
+        skipped.push(path);
+        continue;
+      }
+      if (dryRun) {
+        wouldWrite.push(path);
+        output?.log(`${output.prefix}: would write ${path}`);
+        continue;
+      }
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, SKILL_FILES[file]);
+      written.push(path);
+      output?.log(`${output.prefix}: wrote ${path}`);
+    }
+  }
+
+  if (dryRun) output?.log(`${output.prefix}: dry run: nothing was written (${wouldWrite.length} ${wouldWrite.length === 1 ? 'file' : 'files'})`);
+  else if (written.length === 0) output?.log(`${output.prefix}: the skill is already installed (${plan.filter((target) => !target.source).map((target) => target.path).join(', ')})`);
+
+  return {
+    dry_run: dryRun,
+    targets: plan.map((target) => target.path),
+    files,
+    written,
+    would_write: wouldWrite,
+    skipped,
+    source: plan.filter((target) => target.source).map((target) => target.path),
+  };
+}
+
+/** The first OpenCode configuration of `dir`, in the order OpenCode reads them. */
+export function findProjectConfig(dir) {
+  return OPENCODE_CONFIG_FILES.map((name) => join(dir, name)).find((file) => existsSync(file));
+}
+
+/**
+ * Whether `text` has a // or /* comment outside a string. A URL such as https://ias.imagina.build is not a comment.
+ */
+export function hasJsonComments(text) {
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === '\\') escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"') inString = true;
+    else if (character === '/' && (text[index + 1] === '/' || text[index + 1] === '*')) return true;
+  }
+  return false;
+}
+
+/**
+ * The skill catalog in the project's OpenCode configuration. It creates opencode.jsonc when there is none and merges the
+ * URL into skills when the file is plain JSON. A JSONC file (comments) or one that does not parse is never rewritten:
+ * the exact line to add is returned instead. Returns { file, action, url, line?, changed }.
+ */
+export function ensureSkillConfig(dir, { dryRun = false } = {}) {
+  const file = findProjectConfig(dir);
+  if (!file) {
+    const target = join(dir, OPENCODE_CONFIG_FILES[0]);
+    const config = { $schema: 'https://opencode.ai/config.json', skills: [SKILL_CATALOG_URL] };
+    if (!dryRun) writeFileSync(target, `${JSON.stringify(config, null, 2)}\n`);
+    return { file: target, action: 'created', url: SKILL_CATALOG_URL, changed: true };
+  }
+
+  const text = readFileSync(file, 'utf8');
+  let config;
+  try {
+    config = JSON.parse(text);
+  } catch {
+    return { file, action: 'manual', url: SKILL_CATALOG_URL, line: SKILL_CONFIG_LINE, changed: false };
+  }
+  if (hasJsonComments(text) || !config || typeof config !== 'object' || Array.isArray(config)) {
+    return { file, action: 'manual', url: SKILL_CATALOG_URL, line: SKILL_CONFIG_LINE, changed: false };
+  }
+  if (config.skills !== undefined && !Array.isArray(config.skills)) {
+    return { file, action: 'manual', url: SKILL_CATALOG_URL, line: SKILL_CONFIG_LINE, changed: false };
+  }
+  if (Array.isArray(config.skills) && config.skills.includes(SKILL_CATALOG_URL)) {
+    return { file, action: 'unchanged', url: SKILL_CATALOG_URL, changed: false };
+  }
+
+  config.skills = [...(config.skills ?? []), SKILL_CATALOG_URL];
+  if (!dryRun) writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+  return { file, action: 'updated', url: SKILL_CATALOG_URL, changed: true };
+}
+
+/** The IAS section of AGENTS.md, appended once. Returns { file, action, changed }. */
+export function ensureAgentsSection(dir, { dryRun = false } = {}) {
+  const file = join(dir, AGENTS_FILE);
+  const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (/^## IAS\s*$/m.test(text)) return { file, action: 'unchanged', changed: false };
+  const base = text.length === 0 ? '' : `${text.endsWith('\n') ? text : `${text}\n`}\n`;
+  if (!dryRun) writeFileSync(file, `${base}${AGENTS_SECTION}\n`);
+  return { file, action: text.length === 0 ? 'created' : 'appended', changed: true };
+}
+
+/**
+ * The two halves of the discovery of ias init: the catalog in the OpenCode configuration and the pointer in AGENTS.md.
+ * Returns { config, agents, changed } and prints the plan.
+ */
+export function discoverSkill(dir, { dryRun = false } = {}, output) {
+  const config = ensureSkillConfig(dir, { dryRun });
+  const agents = ensureAgentsSection(dir, { dryRun });
+  const verb = dryRun ? 'would' : '';
+  if (config.action === 'manual') {
+    output?.log(`${output.prefix}: skill: ${config.file} has comments or is not plain JSON, so it is not rewritten; add this line:`);
+    output?.log(`  ${config.line}`);
+  } else if (config.action === 'unchanged') {
+    output?.log(`${output.prefix}: skill: ${config.file} already has the catalog ${SKILL_CATALOG_URL}`);
+  } else {
+    const what = config.action === 'created' ? 'wrote' : 'added the catalog to';
+    output?.log(`${output.prefix}: skill: ${dryRun ? `would write` : what} ${config.file}${config.action === 'updated' ? ` (${SKILL_CATALOG_URL})` : ''}`);
+  }
+  if (agents.action === 'unchanged') {
+    output?.log(`${output.prefix}: skill: ${agents.file} already has the IAS section`);
+  } else {
+    output?.log(`${output.prefix}: skill: ${dryRun ? 'would append' : 'appended'} the IAS section to ${agents.file}`);
+  }
+  return { config, agents, changed: config.changed || agents.changed };
+}
+
+/** Whether the project (its configuration or a skill folder) or this computer already has the skill of IAS. */
+export function hasSkill(dir, env = process.env) {
+  const config = findProjectConfig(dir);
+  if (config && readFileSync(config, 'utf8').includes(SKILL_CATALOG_URL)) return true;
+  const home = homeOf(env);
+  const folders = [
+    join(dir, '.opencode/skills', SKILL_NAME),
+    join(dir, '.claude/skills', SKILL_NAME),
+    join(home, '.config/opencode/skills', SKILL_NAME),
+    join(home, '.opencode/skills', SKILL_NAME),
+    join(home, '.claude/skills', SKILL_NAME),
+  ];
+  return folders.some((folder) => existsSync(join(folder, 'SKILL.md')));
+}
+
+/** The non-blocking hint of ias setup and ias doctor, or undefined when the skill is already there. */
+export function skillHint(dir, env = process.env) {
+  if (hasSkill(dir, env)) return undefined;
+  return 'the agent skill of IAS is not here: ias init adds its catalog to opencode.jsonc, or ias skill install writes .opencode/skills/ias (--global for ~/.config/opencode/skills/ias, --claude for Claude Code)';
+}

package/src/team-vault.mjs

@@ -26,9 +26,9 @@ const ITEM = /^op:\/\/([^/\s]+)\/([^/]+)$/;
  * vault <host>. Returns { reference, vault, title }.
  */
 export function vaultItem(context, project, server) {
-  const reference = context.values?.item ?? context.env.IAS_VAULT_ITEM ?? project?.config?.vault?.item ?? `op://Private/IAS vault ${new URL(server).hostname}`;
+  const reference = context.values?.item ?? context.env.IAS_VAULT_ITEM ?? project?.config?.vault?.item ?? `op://IAS/IAS vault ${new URL(server).hostname}`;
   const match = ITEM.exec(reference);
-  if (!match) throw new IasError(`«${reference}» is not a 1Password item`, { fix: 'it is op://<vault>/<item>, such as op://Private/IAS vault ias.imagina.build' });
+  if (!match) throw new IasError(`«${reference}» is not a 1Password item`, { fix: 'it is op://<vault>/<item>, such as op://IAS/IAS vault ias.imagina.build' });
   return { reference, vault: match[1], title: match[2] };
 }
 

package/src/token-store.mjs

@@ -64,7 +64,7 @@ export function storedToken(server, { env = process.env, kind = storeKind(env) }
 
 /** Keeps `token` for `server`; returns where it went. */
 export function saveToken(server, token, { env = process.env, kind = storeKind(env) } = {}) {
-  if (kind === 'none') throw new IasError('this machine keeps no tokens (CI)', { fix: 'set IAS_TOKEN to a robot token (iasr_…, created in the panel: the application › Settings › Access)' });
+  if (kind === 'none') throw new IasError('this machine keeps no tokens (CI)', { fix: 'set IAS_TOKEN to a robot token (iasr_…): ias tokens create makes one (an owner, kept in 1Password), or the panel: the application › Settings › Access' });
   if (!/^iasp_[A-Za-z0-9_-]{43}$/.test(token)) throw new IasError('the server gave a token that is not a personal token (iasp_…)', { fix: 'run ias login again; if it goes on, check the server' });
   if (kind === 'file') {
     const file = tokenFile(env);