nono-skills 0.1.0

package/src/plugin-install.js

@@ -0,0 +1,135 @@
+import { cp, mkdir, readFile, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { listFiles } from './fs-safe.js';
+import {
+  createOwnershipManifest, readMarketplace, upsertMarketplaceEntry,
+  verifyOwnership, writeJsonAtomic,
+} from './plugin-state.js';
+
+const PLUGIN_NAME = 'engineering';
+const MARKETPLACE_ENTRY = {
+  name: PLUGIN_NAME,
+  source: { source: 'local', path: './plugins/engineering' },
+  policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+  category: 'Developer Tools',
+};
+
+async function exists(file) {
+  try { await stat(file); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+async function readJson(file) {
+  return JSON.parse(await readFile(file, 'utf8'));
+}
+
+function withCachebuster(version, cachebuster) {
+  return `${version.split('+')[0]}+codex.${cachebuster}`;
+}
+
+async function transact(context, requireExisting) {
+  const { home, packageRoot, runCodex, packageVersion } = context;
+  const cachebuster = context.clock();
+  const preflight = await runCodex(['--version']);
+  if (preflight.code !== 0) throw new Error(`Codex CLI is unavailable: ${preflight.stderr || 'version check failed'}`);
+
+  const pluginsRoot = path.join(home, 'plugins');
+  const destination = path.join(pluginsRoot, PLUGIN_NAME);
+  const statePath = path.join(destination, '.installer-state.json');
+  const marketplacePath = path.join(home, '.agents', 'plugins', 'marketplace.json');
+  const oldMarketplace = await readMarketplace(marketplacePath);
+  const destinationExists = await exists(destination);
+  if (requireExisting && !destinationExists) throw new Error('Engineering plugin is not installed');
+
+  let oldState;
+  if (destinationExists) {
+    if (!await exists(statePath)) throw new Error('Existing engineering plugin is not owned by this installer');
+    oldState = await readJson(statePath);
+    const ownership = await verifyOwnership(oldState, destination);
+    if (!ownership.valid) throw new Error(`Existing engineering plugin is not owned safely; changed files: ${ownership.mismatches.join(', ')}`);
+  }
+
+  await mkdir(pluginsRoot, { recursive: true });
+  const stage = path.join(pluginsRoot, `.engineering-stage-${process.pid}-${Date.now()}`);
+  const backup = path.join(pluginsRoot, `.engineering-backup-${process.pid}-${Date.now()}`);
+  let movedExisting = false;
+  let installedStage = false;
+  let registrationSucceeded = false;
+  let registrationMarketplace = oldMarketplace?.name ?? 'personal';
+  try {
+    await cp(path.join(packageRoot, 'plugin'), stage, { recursive: true, errorOnExist: true });
+    const pluginJsonPath = path.join(stage, '.codex-plugin', 'plugin.json');
+    const plugin = await readJson(pluginJsonPath);
+    plugin.version = withCachebuster(plugin.version, cachebuster);
+    await writeJsonAtomic(pluginJsonPath, plugin);
+    const files = await listFiles(stage);
+    const manifest = await createOwnershipManifest({
+      packageVersion,
+      pluginVersion: plugin.version,
+      marketplaceName: oldMarketplace?.name ?? 'personal',
+      root: stage,
+      files,
+    });
+    await writeJsonAtomic(path.join(stage, '.installer-state.json'), manifest);
+
+    if (oldState && JSON.stringify(oldState.files) === JSON.stringify(manifest.files) && oldState.packageVersion === manifest.packageVersion) {
+      const marketplaceResult = upsertMarketplaceEntry(oldMarketplace, MARKETPLACE_ENTRY);
+      if (marketplaceResult.change !== 'unchanged') await writeJsonAtomic(marketplacePath, marketplaceResult.marketplace);
+      const marketplaceName = marketplaceResult.marketplace.name;
+      registrationMarketplace = marketplaceName;
+      const registration = await runCodex(['plugin', 'add', `${PLUGIN_NAME}@${marketplaceName}`]);
+      if (registration.code !== 0) throw new Error(registration.stderr || 'Codex plugin registration failed');
+      registrationSucceeded = true;
+      const verification = await runCodex(['plugin', 'list']);
+      if (verification.code !== 0 || !verification.stdout.includes(`${PLUGIN_NAME}@`)) {
+        throw new Error(verification.stderr || 'Codex plugin verification failed');
+      }
+      await rm(stage, { recursive: true, force: true });
+      return { status: marketplaceResult.change === 'unchanged' ? 'unchanged' : 'repaired', pluginVersion: plugin.version };
+    }
+
+    if (destinationExists) {
+      await rename(destination, backup);
+      movedExisting = true;
+    }
+    await rename(stage, destination);
+    installedStage = true;
+
+    const marketplaceResult = upsertMarketplaceEntry(oldMarketplace, MARKETPLACE_ENTRY);
+    await writeJsonAtomic(marketplacePath, marketplaceResult.marketplace);
+    const marketplaceName = marketplaceResult.marketplace.name;
+    registrationMarketplace = marketplaceName;
+    const registration = await runCodex(['plugin', 'add', `${PLUGIN_NAME}@${marketplaceName}`]);
+    if (registration.code !== 0) throw new Error(registration.stderr || 'Codex plugin registration failed');
+    registrationSucceeded = true;
+    const verification = await runCodex(['plugin', 'list']);
+    if (verification.code !== 0 || !verification.stdout.includes(`${PLUGIN_NAME}@`)) {
+      throw new Error(verification.stderr || 'Codex plugin verification failed');
+    }
+    await rm(backup, { recursive: true, force: true });
+    return { status: destinationExists ? 'updated' : 'installed', pluginVersion: plugin.version };
+  } catch (error) {
+    await rm(stage, { recursive: true, force: true });
+    if (installedStage) await rm(destination, { recursive: true, force: true });
+    if (movedExisting && await exists(backup)) await rename(backup, destination);
+    if (oldMarketplace === null) await rm(marketplacePath, { force: true });
+    else await writeJsonAtomic(marketplacePath, oldMarketplace);
+    if (registrationSucceeded) {
+      const previousEntry = oldMarketplace?.plugins?.find((plugin) => plugin.name === PLUGIN_NAME);
+      const rollback = previousEntry && oldState
+        ? await runCodex(['plugin', 'add', `${PLUGIN_NAME}@${oldMarketplace.name}`])
+        : await runCodex(['plugin', 'remove', `${PLUGIN_NAME}@${registrationMarketplace}`]);
+      if (rollback.code !== 0) throw new Error(`${error.message}; Codex rollback failed: ${rollback.stderr || 'unknown error'}`);
+    }
+    throw error;
+  }
+}
+
+export function installPlugin(context) {
+  return transact(context, false);
+}
+
+export function updatePlugin(context) {
+  return transact(context, true);
+}

package/src/plugin-state.js

@@ -0,0 +1,82 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { listFiles, sha256File } from './fs-safe.js';
+
+export async function readMarketplace(file) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export function upsertMarketplaceEntry(input, entry) {
+  const marketplace = structuredClone(input ?? {
+    name: 'personal', interface: { displayName: 'Personal' }, plugins: [],
+  });
+  marketplace.plugins ??= [];
+  const index = marketplace.plugins.findIndex((plugin) => plugin.name === entry.name);
+  if (index === -1) {
+    marketplace.plugins.push(structuredClone(entry));
+    return { marketplace, change: 'created' };
+  }
+  const existing = marketplace.plugins[index];
+  if (existing.source?.source !== 'local' || existing.source?.path !== entry.source.path) {
+    throw new Error(`Marketplace entry ${entry.name} is not owned by this installer`);
+  }
+  if (JSON.stringify(existing) === JSON.stringify(entry)) return { marketplace, change: 'unchanged' };
+  marketplace.plugins[index] = structuredClone(entry);
+  return { marketplace, change: 'updated' };
+}
+
+export function removeMarketplaceEntry(input, pluginName) {
+  const marketplace = structuredClone(input);
+  const before = marketplace.plugins?.length ?? 0;
+  marketplace.plugins = (marketplace.plugins ?? []).filter((plugin) => plugin.name !== pluginName);
+  return { marketplace, removed: marketplace.plugins.length !== before };
+}
+
+export async function writeJsonAtomic(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, file);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function createOwnershipManifest({ packageVersion, pluginVersion, marketplaceName, root, files }) {
+  const checksums = {};
+  for (const relative of [...files].sort()) checksums[relative] = await sha256File(path.join(root, relative));
+  return {
+    schemaVersion: 1,
+    packageVersion,
+    pluginVersion,
+    marketplaceName,
+    files: checksums,
+  };
+}
+
+export async function verifyOwnership(manifest, root) {
+  const mismatches = [];
+  for (const [relative, expected] of Object.entries(manifest.files ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+    try {
+      if (await sha256File(path.join(root, relative)) !== expected) mismatches.push(relative);
+    } catch (error) {
+      if (error.code === 'ENOENT') mismatches.push(relative);
+      else throw error;
+    }
+  }
+  const expectedFiles = new Set(Object.keys(manifest.files ?? {}));
+  const actualFiles = (await listFiles(root)).filter((relative) => relative !== '.installer-state.json');
+  for (const relative of actualFiles) {
+    if (!expectedFiles.has(relative)) mismatches.push(relative);
+  }
+  mismatches.sort();
+  return { valid: mismatches.length === 0, mismatches };
+}

package/src/project-init.js

@@ -0,0 +1,53 @@
+import { copyFile, mkdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { filesEqual, listFiles } from './fs-safe.js';
+
+async function exists(file) {
+  try {
+    await stat(file);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function planProjectInit({ templateRoot, targetRoot, force = false, dryRun = false, clock = () => new Date().toISOString().replaceAll(/[-:.]/g, '') }) {
+  const files = await listFiles(templateRoot);
+  const actions = [];
+  const stamp = clock();
+  for (const relative of files) {
+    const source = path.join(templateRoot, relative);
+    const destination = path.join(targetRoot, relative);
+    let type = 'create';
+    let backup;
+    if (await exists(destination)) {
+      if (await filesEqual(source, destination)) type = 'skip';
+      else if (force) {
+        type = 'replace';
+        backup = path.join(targetRoot, '.codex-engineering-skills-backup', stamp, relative);
+      } else type = 'conflict';
+    }
+    actions.push({ type, source, destination, relative, backup, dryRun });
+  }
+  return actions;
+}
+
+export async function applyProjectInit(actions) {
+  const results = [];
+  for (const action of actions) {
+    if (action.dryRun || action.type === 'skip' || action.type === 'conflict') {
+      results.push({ ...action, applied: false });
+      continue;
+    }
+    await mkdir(path.dirname(action.destination), { recursive: true });
+    if (action.type === 'replace') {
+      await mkdir(path.dirname(action.backup), { recursive: true });
+      await copyFile(action.destination, action.backup);
+    }
+    await copyFile(action.source, action.destination);
+    results.push({ ...action, applied: true });
+  }
+  return results;
+}

package/src/uninstall.js

@@ -0,0 +1,50 @@
+import { readFile, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { sha256File } from './fs-safe.js';
+import { readMarketplace, removeMarketplaceEntry, verifyOwnership, writeJsonAtomic } from './plugin-state.js';
+
+async function exists(file) {
+  try { await stat(file); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+export async function uninstallPlugin({ home, runCodex }) {
+  const pluginRoot = path.join(home, 'plugins', 'engineering');
+  const statePath = path.join(pluginRoot, '.installer-state.json');
+  if (!await exists(statePath)) throw new Error('Engineering plugin is not owned by this installer');
+  const state = JSON.parse(await readFile(statePath, 'utf8'));
+  const ownership = await verifyOwnership(state, pluginRoot);
+  if (!ownership.valid) throw new Error(`Engineering plugin ownership check failed: ${ownership.mismatches.join(', ')}`);
+
+  const marketplacePath = path.join(home, '.agents', 'plugins', 'marketplace.json');
+  const marketplace = await readMarketplace(marketplacePath);
+  const entry = marketplace?.plugins?.find((plugin) => plugin.name === 'engineering');
+  if (!entry || entry.source?.source !== 'local' || entry.source?.path !== './plugins/engineering') {
+    throw new Error('Engineering marketplace entry is not owned by this installer');
+  }
+
+  const removal = await runCodex(['plugin', 'remove', `engineering@${state.marketplaceName}`]);
+  if (removal.code !== 0) throw new Error(removal.stderr || 'Codex plugin removal failed');
+  const next = removeMarketplaceEntry(marketplace, 'engineering');
+  await writeJsonAtomic(marketplacePath, next.marketplace);
+  await rm(pluginRoot, { recursive: true });
+  return { status: 'uninstalled', projectArtifactsPreserved: true };
+}
+
+export async function purgeProject({ targetRoot, recordedChecksums }) {
+  const removed = [];
+  const preserved = [];
+  for (const [relative, expected] of Object.entries(recordedChecksums).sort(([a], [b]) => a.localeCompare(b))) {
+    const file = path.join(targetRoot, relative);
+    try {
+      if (await sha256File(file) === expected) {
+        await rm(file);
+        removed.push(relative);
+      } else preserved.push(relative);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  return { removed, preserved };
+}

package/templates/AGENTS.md

@@ -0,0 +1,48 @@
+# Repository Guidance
+
+Keep this file specific to the repository. Replace placeholders with commands and conventions that are true here; remove sections that do not apply.
+
+## Repository facts
+
+- Setup:
+- Lint:
+- Typecheck:
+- Test:
+- Build:
+- Important directories:
+
+## Durable rules
+
+- Treat executable code, configuration, tests, migrations, and observed behavior as stronger evidence than stale prose.
+- Preserve unrelated behavior and backward compatibility unless the requirement changes it.
+- Keep external writes, commits, pushes, merges, releases, deployments, and production mutations behind explicit user authorization.
+- Verify changed behavior with the strongest safe repository checks available. Report what ran and what remains unverified.
+
+## Task artifacts
+
+Use existing files under `docs/agent/` only when they help the current task:
+
+- `spec.md`: goal, scope, constraints, acceptance criteria, and unresolved product choices
+- `plan.md`: current execution map, status, dependencies, and verification targets
+- `decision-log.md`: material decisions, evidence, alternatives, and consequences
+- `findings.md`: review findings and their lifecycle
+- `handoff.md`: resumable state when work remains or ownership changes
+
+Do not create missing workflow artifacts unless the user requests durable artifacts or runs `npx nono-skills init`. Without them, put the same material information in the final response.
+
+Append a decision only when it changes a contract, resolves meaningful ambiguity, accepts risk or a costly tradeoff, changes the plan materially, or records an assumption future work must preserve. Supersede accepted entries instead of rewriting history. Do not log routine edits or shell commands.
+
+## Definition of done
+
+- The requested outcome and acceptance criteria are satisfied.
+- Relevant targeted checks pass, followed by broader checks in proportion to risk.
+- Compatibility, migration, security, and operational effects are addressed when applicable.
+- Remaining risks, blockers, and unverified assumptions are explicit.
+
+## Project conventions
+
+Add architecture boundaries, naming rules, generated-file policy, release procedures, ownership, and recurring review guidance here only after they become repository facts.
+
+## Skills
+
+Let Codex select the smallest applicable set, or invoke one explicitly as `$engineering:<skill>` such as `$engineering:plan` or `$engineering:review`. Skills provide task-specific process; this file provides repository-specific truth.

package/templates/docs/agent/decision-log.md

@@ -0,0 +1,15 @@
+# Decision Log
+
+Append material decisions. Never silently rewrite an accepted decision; supersede it with a new entry.
+
+## YYYY-MM-DD HH:MM — Decision title
+
+- Status: proposed | accepted | superseded | rejected
+- Context:
+- Decision:
+- Alternatives:
+- Evidence and rationale:
+- Consequences:
+- Follow-up:
+- Related:
+

package/templates/docs/agent/findings.md

@@ -0,0 +1,13 @@
+# Findings
+
+## Finding ID — Short title
+
+- Severity: critical | high | medium | low
+- State: open | accepted | fixed | verified | wont-fix | not-reproducible
+- Evidence:
+- Impact:
+- Reproduction or reasoning:
+- Remediation direction:
+- Verification:
+- Owner or follow-up:
+

package/templates/docs/agent/handoff.md

@@ -0,0 +1,20 @@
+# Agent Handoff
+
+## Objective
+
+## Current status
+
+## Completed
+
+## In progress
+
+## Remaining
+
+## Decisions and assumptions
+
+## Blockers and human input
+
+## Verification performed
+
+## Resume from here
+

package/templates/docs/agent/plan.md

@@ -0,0 +1,14 @@
+# Working Plan
+
+Status values: `pending`, `in-progress`, `blocked`, `done`.
+
+| Status | Work item | Verification | Notes |
+|---|---|---|---|
+| pending |  |  |  |
+
+## Risks and dependencies
+
+## Human decisions needed
+
+## Latest checkpoint
+

package/templates/docs/agent/spec.md

@@ -0,0 +1,20 @@
+# Working Spec
+
+## Goal
+
+## Users and outcome
+
+## In scope
+
+## Out of scope
+
+## Constraints
+
+## Acceptance criteria
+
+- [ ]
+
+## Open questions
+
+## Evidence and references
+