aas-setup 1.0.1

package/configs/reference/git-guidelines.md

@@ -0,0 +1,62 @@
+# Git Safety Guidelines
+
+## Safe Git Operations
+
+AI agents should follow these principles when working with git:
+
+### ✅ Allowed Operations
+
+- **Read operations**: `git status`, `git log`, `git diff`, `git show`
+- **Safe commits**: `git add`, `git commit`
+- **Branch management**: `git branch`, `git checkout -b`, `git switch`
+- **Safe push**: `git push` (standard push without force)
+- **Inspection**: `git blame`, `git ls-files`, `git rev-parse`
+
+### ⛔ Operations to Avoid
+
+Avoid these dangerous git commands without explicit user approval:
+
+- **Add all files**: `git add -A`, `git add --all` (stages all changes including untracked files; prefer `git add <specific-files>` or `git add -p` for interactive staging)
+- **Force push**: `git push --force`, `git push -f` (not recommended; if absolutely required, `--force-with-lease` is safer)
+- **History rewriting**: `git rebase -i`, `git filter-branch`
+- **Amending pushed commits**: `git commit --amend` (only safe for local, unpushed commits)
+- **Reset operations**: `git reset`, `git reset --hard`, `git reset --mixed`, `git reset --soft` (unstages files or moves HEAD; can lose work or change history)
+- **Force operations**: `git checkout --force`, `git clean -f/-d`, `git branch -D`
+- **Stash deletion**: `git stash drop`, `git stash clear`
+- **Reference manipulation**: `git update-ref -d`, `git reflog expire`
+
+### Best Practices
+
+- Always use `git --no-pager` to prevent interactive pagers in scripts
+- Check repository state with `git status` before operations
+- Stage files intentionally: use `git add <specific-files>` or `git add -p` for interactive staging
+- Use `git diff` to verify changes before committing
+- Prefer `git switch` over `git checkout` for branch switching (Git 2.23+; use `git checkout <branch>` for older versions)
+- Use descriptive commit messages following conventional commits format
+- Create feature branches instead of working directly on main/master
+- Pull before push to avoid conflicts: `git pull origin <branch>` (or `git fetch origin && git merge origin/<branch>` for more control)
+
+### Error Handling
+
+```bash
+# Check if git repository
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    echo "Error: Not a git repository" >&2
+    exit 1
+fi
+
+# Check for uncommitted changes
+if ! git diff-index --quiet HEAD --; then
+    echo "Warning: Uncommitted changes detected" >&2
+fi
+```
+
+## Pre-commit Checklist
+
+- [ ] Shell scripts pass `bash -n` syntax check
+- [ ] Tested with `--dry-run`
+- [ ] No absolute paths in configs
+- [ ] Colors and logging functions used consistently
+- [ ] Error handling with `set -e` and guard clauses
+- [ ] Documentation updated if workflow changed
+- [ ] Git operations follow safety guidelines

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "aas-setup",
+	"version": "1.0.1",
+	"description": "Initialize Pi and OpenCode agent environments from a curated snapshot",
+	"type": "module",
+	"bin": {
+		"aas-setup": "./bin/aas-setup.mjs"
+	},
+	"files": [
+		"bin",
+		"src",
+		"configs"
+	],
+	"scripts": {
+		"test": "node --test",
+		"dev": "node bin/aas-setup.mjs"
+	},
+	"keywords": [
+		"cli",
+		"pi",
+		"opencode",
+		"agent-setup"
+	],
+	"author": "kk",
+	"license": "MIT",
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.1"
+	},
+	"dependencies": {
+		"@inquirer/prompts": "^7.10.1",
+		"chalk": "^5.3.0",
+		"commander": "^12.0.0"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	}
+}

package/src/agents/opencode.mjs

@@ -0,0 +1,22 @@
+// opencode.mjs — OpenCode agent descriptor.
+// Pure data; the initializer in src/commands/init.mjs loops over a list of
+// these. Paths with ~ are expanded at runtime by the initializer.
+
+/** @type {import('./types.mjs').AgentDescriptor} */
+export const opencode = {
+	id: "opencode",
+	name: "OpenCode",
+	home: "~/.config/opencode",
+	configSource: "configs/opencode",
+	referenceDest: "~/.config/opencode/aas-setup",
+	install: {
+		kind: "curl",
+		url: "https://opencode.ai/install",
+		bin: "opencode",
+	},
+	deploy: {
+		overwriteFiles: ["opencode.json"],
+		replaceDirs: ["agent", "command"],
+		referenceSource: "configs/reference",
+	},
+};

package/src/agents/pi.mjs

@@ -0,0 +1,22 @@
+// pi.mjs — Pi agent descriptor.
+// Pure data; the initializer in src/commands/init.mjs loops over a list of
+// these. Paths with ~ are expanded at runtime by the initializer.
+
+/** @type {import('./types.mjs').AgentDescriptor} */
+export const pi = {
+	id: "pi",
+	name: "Pi",
+	home: "~/.pi/agent",
+	configSource: "configs/pi",
+	referenceDest: "~/.pi/agent/aas-setup",
+	install: {
+		kind: "npm",
+		pkg: "@mariozechner/pi-coding-agent",
+		bin: "pi",
+	},
+	deploy: {
+		overwriteFiles: ["settings.json", "mcp.json", "models.json", "AGENTS.md"],
+		replaceDirs: ["themes"],
+		referenceSource: "configs/reference",
+	},
+};

package/src/agents/types.mjs

@@ -0,0 +1,30 @@
+// types.mjs — JSDoc type shapes for agent descriptors.
+// No runtime exports; used only for type hints in editors.
+
+/**
+ * @typedef {Object} InstallSpec
+ * @property {"npm"|"curl"} kind
+ * @property {string} [pkg]      — npm package name (kind === "npm")
+ * @property {string} [url]      — curl install URL (kind === "curl")
+ * @property {string} bin        — binary name to detect on PATH
+ */
+
+/**
+ * @typedef {Object} DeploySpec
+ * @property {string[]} overwriteFiles  — files copied flat into home
+ * @property {string[]} replaceDirs     — subdirs rm-rf'd then fully replaced
+ * @property {string} referenceSource   — package-relative path to reference docs
+ */
+
+/**
+ * @typedef {Object} AgentDescriptor
+ * @property {string} id
+ * @property {string} name
+ * @property {string} home             — ~-prefixed agent home
+ * @property {string} configSource     — package-relative path to agent configs
+ * @property {string} referenceDest    — ~-prefixed destination for reference docs
+ * @property {InstallSpec} install
+ * @property {DeploySpec} deploy
+ */
+
+export {};

package/src/commands/init.mjs

@@ -0,0 +1,99 @@
+// init.mjs — the initializer.
+// Loops over the two agent descriptors and runs detect → install → (backup)
+// → deploy-configs → deploy-reference. Each step honors { dryRun }.
+
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { opencode } from "../agents/opencode.mjs";
+import { pi } from "../agents/pi.mjs";
+import { detectBinary, runCommand } from "../lib/exec.mjs";
+import { backupToTar, copyDir, copyDirFiles, copyFile, ensureDir, rmrf } from "../lib/fs.mjs";
+import { log } from "../lib/log.mjs";
+import { expandHome, packageRoot, pkgPath } from "../lib/paths.mjs";
+
+const AGENTS = [pi, opencode];
+
+export { AGENTS };
+
+/** Directory for --backup tars: ~/ai-tools-backup-<timestamp>/ */
+function backupDirFor() {
+	const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+	return resolve(homedir(), `ai-tools-backup-${ts}`);
+}
+
+/**
+ * Install step: detect the agent's binary on PATH; if missing, run the
+ * install command. No-op (print only) in dry-run.
+ */
+async function installStep(agent, { dryRun }) {
+	const present = dryRun ? false : detectBinary(agent.install.bin);
+	if (present) {
+		if (!dryRun) log.skip(agent.name);
+		else log.dry(`detect ${agent.install.bin} (assume present → skip)`);
+		return 0;
+	}
+	// install
+	const cmdline = installCmdline(agent.install);
+	if (dryRun) {
+		log.dry(`detect ${agent.install.bin} → missing → install`);
+	}
+	log.install(agent.name);
+	return runCommand(cmdline, { dryRun });
+}
+
+function installCmdline(spec) {
+	if (spec.kind === "npm") return `npm install -g ${spec.pkg}`;
+	if (spec.kind === "curl") return `curl -fsSL ${spec.url} | bash`;
+	throw new Error(`unknown install kind: ${spec.kind}`);
+}
+
+/**
+ * Deploy agent configs: overwrite flat files, replace subdirs wholesale.
+ */
+function deployConfigs(agent, pkgRoot, { dryRun }) {
+	const home = expandHome(agent.home);
+	const srcDir = pkgPath(pkgRoot, agent.configSource);
+	ensureDir(home, { dryRun });
+	for (const file of agent.deploy.overwriteFiles) {
+		copyFile(resolve(srcDir, file), resolve(home, file), { dryRun });
+	}
+	for (const dir of agent.deploy.replaceDirs) {
+		copyDir(resolve(srcDir, dir), resolve(home, dir), { dryRun });
+	}
+}
+
+function deployReference(agent, pkgRoot, { dryRun }) {
+	const dest = expandHome(agent.referenceDest);
+	const src = pkgPath(pkgRoot, agent.deploy.referenceSource);
+	ensureDir(dest, { dryRun });
+	copyDirFiles(src, dest, { dryRun });
+}
+
+/**
+ * Back up the agent's existing home to a tar (no-op if absent).
+ */
+function backupAgentHome(agent, backupDir, { dryRun }) {
+	backupToTar(expandHome(agent.home), backupDir, { dryRun });
+}
+
+/**
+ * Initialize both Pi and OpenCode. Returns 0 on success, non-zero on failure.
+ *
+ * @param {{ dryRun?: boolean, backup?: boolean }} opts
+ * @returns {Promise<number>}
+ */
+export async function initialize({ dryRun = false, backup = false, agents = AGENTS } = {}) {
+	const pkgRoot = packageRoot(import.meta.url);
+	const backupDir = backup ? backupDirFor() : null;
+	log.info(dryRun ? "Dry-run mode — no changes will be made" : "Initializing agent environments");
+	if (backup) log.info(`Backing up existing agent homes to ${backupDir}`);
+	for (const agent of agents) {
+		log.step(`Configure ${agent.name}`);
+		await installStep(agent, { dryRun });
+		if (backup) backupAgentHome(agent, backupDir, { dryRun });
+		deployConfigs(agent, pkgRoot, { dryRun });
+		deployReference(agent, pkgRoot, { dryRun });
+	}
+	log.success("Setup complete");
+	return 0;
+}

package/src/commands/select.mjs

@@ -0,0 +1,52 @@
+// select.mjs — resolve which agents to configure.
+//
+// Resolution order:
+//   1. positional args (aas-setup pi opencode) → validate ids, use exactly those
+//   2. non-TTY (CI / piped)                  → all agents, no prompt
+//   3. TTY                                    → interactive multi-select,
+//                                                both pre-checked by default
+//
+// Exits non-zero on unknown agent ids.
+
+import { checkbox } from "@inquirer/prompts";
+import { log } from "../lib/log.mjs";
+import { AGENTS } from "./init.mjs";
+
+const VALID_IDS = new Set(AGENTS.map((a) => a.id));
+
+export async function selectAgents(positional, { tty = false } = {}) {
+	// 1. explicit positional args
+	if (positional.length > 0) {
+		const invalid = positional.filter((id) => !VALID_IDS.has(id));
+		if (invalid.length > 0) {
+			log.error(`Unknown agent(s): ${invalid.join(", ")}`);
+			log.info(`Valid ids: ${AGENTS.map((a) => a.id).join(", ")}`);
+			process.exit(1);
+		}
+		return positional;
+	}
+
+	// 2. non-interactive: all agents
+	if (!tty) {
+		log.info("Non-interactive mode — configuring all agents");
+		return AGENTS.map((a) => a.id);
+	}
+
+	// 3. interactive multi-select
+	const selected = await checkbox({
+		message: "Select agents to configure:",
+		default: true,
+		choices: AGENTS.map((a) => ({
+			name: a.name,
+			value: a.id,
+			checked: true,
+		})),
+	});
+
+	if (selected.length === 0) {
+		log.warning("No agents selected — nothing to do");
+		process.exit(0);
+	}
+
+	return selected;
+}

package/src/lib/exec.mjs

@@ -0,0 +1,35 @@
+// exec.mjs — exec + detect helpers that honor --dry-run.
+//
+// runCommand takes a single shell command string. In dry-run mode it prints
+// "[dry] <cmd>" instead of spawning. In real mode it spawns with shell:true
+// and inherited stdio, returning the exit code.
+
+import { spawn, spawnSync } from "node:child_process";
+
+/**
+ * Run a shell command. If dryRun is true, only print the command.
+ * Returns 0 on success, non-zero on failure. Resolves a Promise.
+ */
+export function runCommand(cmdline, { dryRun = false, cwd } = {}) {
+	if (dryRun) {
+		console.log(`[dry] ${cmdline}`);
+		return Promise.resolve(0);
+	}
+	return new Promise((resolve) => {
+		const child = spawn(cmdline, { cwd, stdio: "inherit", shell: true });
+		child.on("close", (code) => resolve(code ?? 1));
+		child.on("error", () => resolve(1));
+	});
+}
+
+/**
+ * Detect whether a binary is on PATH. Synchronous — used by the detect step
+ * to decide install-vs-skip. Returns boolean.
+ */
+export function detectBinary(name) {
+	const result = spawnSync("command", ["-v", name], {
+		shell: true,
+		stdio: "ignore",
+	});
+	return result.status === 0;
+}

package/src/lib/fs.mjs

@@ -0,0 +1,107 @@
+// fs.mjs — filesystem helpers for deploy.
+// All functions take an optional { dryRun } option: when true, print the
+// planned action with full paths and do NOT touch the filesystem.
+
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+import { log } from "./log.mjs";
+
+/** Strip the leading home directory from an absolute path for nicer tar names. */
+function stripHome(p) {
+	const h = homedir();
+	return p.startsWith(h) ? p.slice(h.length).replace(/^\/+/, "") : p;
+}
+
+/**
+ * Ensure a directory exists (recursive). Prints in dry-run.
+ */
+export function ensureDir(dir, { dryRun = false } = {}) {
+	if (dryRun) {
+		log.dry(`mkdir -p ${dir}`);
+		return;
+	}
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+		log.info(`mkdir ${dir}`);
+	}
+}
+
+/**
+ * Remove a directory recursively. No-op if it doesn't exist. Prints in dry-run.
+ */
+export function rmrf(dir, { dryRun = false } = {}) {
+	if (dryRun) {
+		if (existsSync(dir)) log.dry(`rm -rf ${dir}`);
+		return;
+	}
+	if (existsSync(dir)) {
+		rmSync(dir, { recursive: true, force: true });
+		log.info(`rm -rf ${dir}`);
+	}
+}
+
+/**
+ * Copy a single file, creating parent dirs as needed. Prints in dry-run.
+ */
+export function copyFile(src, dest, { dryRun = false } = {}) {
+	if (dryRun) {
+		log.dry(`cp ${src} → ${dest}`);
+		return;
+	}
+	ensureDir(dirname(dest), { dryRun: false });
+	cpSync(src, dest, { force: true });
+	log.deploy(dest);
+}
+
+/**
+ * Copy a directory recursively, fully replacing the destination.
+ * Calls rmrf(dest) then copies src → dest. Prints in dry-run.
+ */
+export function copyDir(src, dest, { dryRun = false } = {}) {
+	if (dryRun) {
+		log.dry(`rm -rf ${dest} && cp -r ${src} ${dest}`);
+		return;
+	}
+	rmrf(dest, { dryRun: false });
+	ensureDir(dirname(dest), { dryRun: false });
+	cpSync(src, dest, { recursive: true, force: true });
+	log.deploy(dest);
+}
+
+/**
+ * Copy every file in sourceDir (non-recursively) into destDir.
+ * Used to deploy reference docs (flat file set). Prints in dry-run.
+ */
+export function copyDirFiles(sourceDir, destDir, { dryRun = false } = {}) {
+	if (!existsSync(sourceDir)) return;
+	const entries = readdirSync(sourceDir);
+	for (const entry of entries) {
+		const src = resolve(sourceDir, entry);
+		const stat = statSync(src);
+		if (stat.isFile()) {
+			copyFile(src, resolve(destDir, entry), { dryRun });
+		}
+	}
+}
+
+/**
+ * Back up a directory tree to a tar file under backupDir.
+ * Skips silently if the source does not exist. Prints in dry-run.
+ * Returns the created tar path (or null if skipped/no-op).
+ */
+export function backupToTar(src, backupDir, { dryRun = false } = {}) {
+	if (!existsSync(src)) return null;
+	const base = basename(stripHome(src));
+	const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+	const tar = resolve(backupDir, `${base}-${ts}.tar.gz`);
+	if (dryRun) {
+		log.dry(`backup ${src} → ${tar}`);
+		return tar;
+	}
+	ensureDir(backupDir, { dryRun: false });
+	execFileSync("tar", ["-czf", tar, "-C", dirname(src), base], { stdio: "ignore" });
+	log.info(`backup ${src} → ${tar}`);
+	return tar;
+}

package/src/lib/log.mjs

@@ -0,0 +1,39 @@
+// log.mjs — structured stdout logger built on chalk.
+// Every action prints a full resolved path so the user can see exactly what
+// the CLI did.
+
+import chalk from "chalk";
+
+function fullPath(p) {
+	return typeof p === "string" ? p : String(p);
+}
+
+export const log = {
+	info(msg) {
+		console.log(`${chalk.cyan("ℹ")} ${msg}`);
+	},
+	success(msg) {
+		console.log(`${chalk.green("✓")} ${msg}`);
+	},
+	warning(msg) {
+		console.log(`${chalk.yellow("⚠")} ${msg}`);
+	},
+	error(msg) {
+		console.error(`${chalk.red("✗")} ${msg}`);
+	},
+	dry(msg) {
+		console.log(`${chalk.magenta("[dry]")} ${msg}`);
+	},
+	step(msg) {
+		console.log(`${chalk.dim("─")} ${msg}`);
+	},
+	install(name) {
+		console.log(`${chalk.cyan("ℹ")} Installing ${name}...`);
+	},
+	skip(name) {
+		console.log(`${chalk.dim("•")} ${name} already installed, skipping`);
+	},
+	deploy(dest) {
+		console.log(`${chalk.green("✓")} Deployed → ${fullPath(dest)}`);
+	},
+};

package/src/lib/paths.mjs

@@ -0,0 +1,47 @@
+// paths.mjs — resolve package root and agent homes.
+// Resolves from import.meta.url (NOT process.cwd()) so `npx aas-setup` works
+// regardless of the user's current directory.
+
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Resolve the package root (the directory containing bin/, src/, configs/).
+ * Pass import.meta.url from the calling module.
+ */
+export function packageRoot(importMetaUrl) {
+	const here = dirname(fileURLToPath(importMetaUrl));
+	// src/lib/paths.mjs → up two = package root
+	return resolve(here, "..", "..");
+}
+
+/**
+ * Resolve a path inside the package root. Segments are package-relative
+ * (e.g. "configs", "pi", "settings.json"). Descriptors already carry the
+ * "configs/<agent>" prefix, so this does NOT add a magic "configs/".
+ */
+export function pkgPath(pkgRoot, ...segments) {
+	return resolve(pkgRoot, ...segments);
+}
+
+/**
+ * Expand a leading ~ to the user's home directory.
+ */
+export function expandHome(p) {
+	if (!p) return p;
+	if (p === "~") return homedir();
+	if (p.startsWith("~/")) return resolve(homedir(), p.slice(2));
+	return p;
+}
+
+/**
+ * The two agent homes, as absolute paths.
+ */
+export function agentHomes() {
+	const home = homedir();
+	return {
+		pi: resolve(home, ".pi", "agent"),
+		opencode: resolve(home, ".config", "opencode"),
+	};
+}