@aetheros/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hariprasath Thanarajah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/aether.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync, realpathSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { checkProject, installKit, KITS, gitHooksStatus, installGitHooks, uninstallGitHooks, GROUPS, addIdea, addOwnerItem, completeOwnerItem, decideIdea, ownerSummary, planIdea, readOwner } from '@aetheros/workflow';
+import { installClaudeCodeTemplates } from '@aetheros/provider-claude';
+import { installOpenAITemplates } from '@aetheros/provider-openai';
+import { approveSpec, checkSpecRecords, evaluateApprovedSpecGate, linkSpec, listSpecs, specStatus } from '@aetheros/spec-kit';
+const flag = (args, name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const describe = s => `${s.spec}: ${s.approved ? 'approved by ' + s.approvedBy : s.stale ? 'changed since approval (' + s.changed.join(', ') + ')' : s.ready ? 'ready, not approved' : 'missing ' + s.missing.join(', ')}${s.feature ? ' | ' + s.feature : ''}${s.issue ? ' | #' + s.issue : ''}`;
+import { checkMachine, setup } from '../src/setup.js';
+import { runSprint } from '../src/sprint.js';
+import { setupMachine } from '../src/machine.js';
+import { createInterface } from 'node:readline/promises';
+import { installMcpTemplates } from '@aetheros/provider-claude';
+// Run only when started directly. Compare real paths: npm's bin folder and folders such as macOS /var are symlinks,
+// while import.meta.url is always the real file.
+const isMain = (() => { try { return !!process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href; } catch { return false; } })();
+const INSTALLERS = { ...Object.fromEntries(Object.keys(KITS).map(k => [k, (root, o) => installKit(k, root, o)])), githooks: (root, o) => installGitHooks(root, o), claude: installClaudeCodeTemplates, openai: installOpenAITemplates, mcp: installMcpTemplates };
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const CONFIG = 'aether.config.json';
+export function run(args, cwd = process.cwd(), log = console.log) {
+  const [command] = args;
+  const file = resolve(cwd, CONFIG);
+  if (command === 'init') {
+    if (existsSync(file)) throw new Error('Configuration already exists; refusing to overwrite');
+    const config = {schemaVersion:1,project:{name:basename(cwd)},providers:['claude','openai'],approval:'writes'};
+    writeFileSync(file, JSON.stringify(config,null,2)+'\n', {flag:'wx'});
+    log('Created '+file);
+    return;
+  }
+  if (command === 'version' || command === '--version') { log(VERSION); return; }
+  if (command === 'doctor' && args[1] === 'machine') {
+    const { ok, results } = checkMachine();
+    for (const r of results) log(`${r.ok ? 'ok      ' : r.required ? 'MISSING ' : 'optional'} ${r.name}${r.version ? ' ' + r.version : ''}${r.hint && !r.ok ? ' — ' + r.hint : ''}`);
+    if (!ok) throw new Error('Required tools are missing');
+    log('This computer is ready.');
+    return;
+  }
+  if (command === 'doctor' || command === 'status') {
+    if (!existsSync(file)) throw new Error('Missing aether.config.json; run aether init');
+    const config = JSON.parse(readFileSync(file,'utf8'));
+    if (config.schemaVersion !== 1 || !config.project || typeof config.project.name !== 'string' || !Array.isArray(config.providers) || !['always','writes','never'].includes(config.approval) || config.providers.some(p => !['claude','openai'].includes(p))) throw new Error('Invalid AetherOS configuration');
+    log(command === 'doctor' ? 'Configuration valid: '+config.project.name : JSON.stringify({project:config.project.name,providers:config.providers,approval:config.approval},null,2));
+    return;
+  }
+  if (command === 'install') {
+    const kits = args.slice(1).filter(a => !a.startsWith('--'));
+    const dryRun = args.includes('--dry-run');
+    if (!kits.length || kits.some(k => !INSTALLERS[k])) throw new Error('Usage: aether install <' + Object.keys(INSTALLERS).join('|') + '>... [--dry-run]');
+    for (const kit of kits) {
+      const { created, skipped } = INSTALLERS[kit](cwd, { dryRun });
+      for (const f of created) log((dryRun ? 'would create ' : 'created ') + f);
+      for (const f of skipped) log('kept existing ' + f);
+    }
+    return;
+  }
+  if (command === 'githooks') {
+    const sub = args[1] || 'status';
+    if (sub === 'install') { const r = installGitHooks(cwd, { force: args.includes('--force'), dryRun: args.includes('--dry-run') }); for (const f of r.created) log((r.dryRun ? 'would create ' : 'created ') + f); log((r.dryRun ? 'would set' : 'set') + ' core.hooksPath to ' + r.hooksPath); return; }
+    if (sub === 'uninstall') { log(uninstallGitHooks(cwd).removed ? 'AetherOS git hooks turned off (files kept)' : 'AetherOS git hooks were not active'); return; }
+    if (sub === 'status') { const s = gitHooksStatus(cwd); log(s.installed ? 'AetherOS git hooks are active' : 'AetherOS git hooks are not active' + (s.hooksPath ? ` (core.hooksPath is ${s.hooksPath})` : '')); return; }
+    throw new Error('Usage: aether githooks <install [--force] [--dry-run]|uninstall|status>');
+  }
+  if (command === 'owner') {
+    const [, sub, ...rest] = args;
+    const words = rest.filter((a, i) => !a.startsWith('--') && !(i > 0 && rest[i - 1].startsWith('--')));
+    if (sub === 'add') { const item = addOwnerItem(cwd, { group: words[0], task: words.slice(1).join(' '), detail: flag(args, '--detail'), link: flag(args, '--link'), source: flag(args, '--source') }); log(`added ${item.id}: [${item.group}] ${item.task}`); return; }
+    if (sub === 'done') { const item = completeOwnerItem(cwd, words[0], { note: flag(args, '--note') }); log(`done ${item.id}: ${item.task}`); return; }
+    if (sub === 'list' || !sub) {
+      if (args.includes('--all')) { for (const i of readOwner(cwd).items) log(`${i.id} ${i.status.padEnd(4)} [${i.group}] ${i.task}`); return; }
+      const s = ownerSummary(cwd);
+      if (!s.openCount) log('Nothing is waiting on the owner.');
+      for (const g of s.open) { log(g.group + ':'); for (const i of g.items) log(`  ${i.id} ${i.task}${i.link ? ' — ' + i.link : ''}`); }
+      if (s.toDecide.length) log(`Ideas to decide: ${s.toDecide.length} (aether idea list)`);
+      return;
+    }
+    throw new Error('Usage: aether owner <list [--all]|add <' + GROUPS.join('|') + '> <task> [--detail ..] [--link ..]|done <id> [--note ..]>');
+  }
+  if (command === 'idea') {
+    const [, sub, ...rest] = args;
+    const words = rest.filter((a, i) => !a.startsWith('--') && !(i > 0 && rest[i - 1].startsWith('--')));
+    if (sub === 'add') { const idea = addIdea(cwd, { title: words.join(' '), why: flag(args, '--why') }); log(`added idea ${idea.id}: ${idea.title} (waiting for the owner's decision)`); return; }
+    if (sub === 'approve' || sub === 'reject') { const idea = decideIdea(cwd, words[0], sub === 'approve' ? 'Approved' : 'Rejected', { note: flag(args, '--note') }); log(`${idea.status.toLowerCase()}: ${idea.title}`); return; }
+    if (sub === 'plan') { const idea = planIdea(cwd, words[0], { issue: Number(flag(args, '--issue')) }); log(`planned: ${idea.title} → #${idea.issue}`); return; }
+    if (sub === 'list' || !sub) { const { ideas } = readOwner(cwd); if (!ideas.length) log('No ideas yet.'); for (const i of ideas) log(`${i.id} ${i.status.padEnd(9)} ${i.title}${i.issue ? ' #' + i.issue : ''}`); return; }
+    throw new Error('Usage: aether idea <list|add <title> [--why ..]|approve <id>|reject <id>|plan <id> --issue <n>>');
+  }
+  if (command === 'spec') {
+    const [, sub, path] = args;
+    if (sub === 'list') { const all = listSpecs(cwd); if (!all.length) log('no specs/ directories'); for (const s of all) log(describe(s)); return; }
+    if (!path || !['status', 'link', 'approve', 'gate'].includes(sub)) throw new Error('Usage: aether spec <list|status <path>|link <path> [--feature <dir>] [--issue <n>]|approve <path> --by <name>|gate <path>>');
+    if (sub === 'status') { log(describe(specStatus(cwd, path))); return; }
+    if (sub === 'link') { const issue = flag(args, '--issue'); linkSpec(cwd, path, { feature: flag(args, '--feature'), issue: issue === undefined ? undefined : Number(issue) }); log(describe(specStatus(cwd, path))); return; }
+    if (sub === 'approve') { approveSpec(cwd, path, { approver: flag(args, '--by') }); log(describe(specStatus(cwd, path))); return; }
+    const { ok, reasons } = evaluateApprovedSpecGate(cwd, path);
+    if (!ok) throw new Error('Spec gate closed for ' + path + ': ' + reasons.join('; '));
+    log('spec gate open: ' + path);
+    return;
+  }
+  if (command === 'check') {
+    const specProblems = checkSpecRecords(cwd).problems;
+    for (const p of specProblems) log('problem: ' + p);
+    const { ok, problems } = checkProject(cwd);
+    for (const p of problems) log('problem: ' + p);
+    if (!ok || specProblems.length) throw new Error(problems.length + specProblems.length + ' workflow problem(s)');
+    log('workflow docs ok');
+    return;
+  }
+  throw new Error('Usage: aether <start [--reset|--where|--no-open|--no-voice|--launchers]|init|doctor|status|install <kit>...|check|spec ...|run <pack>|run init <dir>|room [serve|snapshot|html <file>|install-vscode]|owner ...|idea ...|githooks <install|uninstall|status>|setup [--yes|--kits a,b] [--os-name ..] [--assistant ..] [--accent #hex] [--dry-run]|setup machine [--install [--yes]]|doctor machine|version|sprint <status|plan|close>|voice [--ai provider] [--model id|--tier t] [--agents [--agent id]] [--pack dir]|workspace [init] [--no-memory] [--no-price-refresh]|models [list|pick --tier cheap|balanced|strong|init|prices [update]]>');
+}
+if (isMain && process.argv[2] === 'start') {
+  import('../src/start.js').then(m => m.start(process.argv.slice(3), process.cwd())).catch(error => { console.error(error.message); process.exitCode = 1; });
+} else if (isMain && process.argv[2] === 'sprint') {
+  runSprint(process.argv.slice(3), process.cwd(), console.log).catch(error => { console.error(error.message); process.exitCode = 1; });
+} else if (isMain && process.argv[2] === 'setup') {
+  (process.argv[3] === 'machine'
+    ? (async () => { const rl = createInterface({ input: process.stdin, output: process.stdout }); try { await setupMachine({ install: process.argv.includes('--install'), yes: process.argv.includes('--yes'), ask: q => rl.question(q), log: console.log }); } finally { rl.close(); } })()
+    : setup(process.argv.slice(3), process.cwd(), console.log, { installers: INSTALLERS })).catch(error => { console.error(error.message); process.exitCode = 1; });
+} else if (isMain && ['run', 'room', 'voice', 'workspace', 'models'].includes(process.argv[2])) {
+  import({ run: '@aetheros/runner/cli', room: '@aetheros/control-room/cli', voice: '@aetheros/voice/cli', workspace: '@aetheros/workspace/cli', models: '@aetheros/models/cli' }[process.argv[2]]).then(m => m.run(process.argv.slice(3))).then(code => { process.exitCode = code; }, error => { console.error(error.message); process.exitCode = 1; });
+} else if (isMain) {
+  try { run(process.argv.slice(2)); } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@aetheros/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abigshana/AetherOS.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "aether": "./bin/aether.js"
+  },
+  "scripts": {
+    "check": "node --check bin/aether.js && node --check src/setup.js && node --check src/sprint.js && node --check src/machine.js && node --check src/start.js",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@aetheros/workflow": "0.1.1",
+    "@aetheros/provider-claude": "0.1.1",
+    "@aetheros/provider-openai": "0.1.1",
+    "@aetheros/spec-kit": "0.1.1",
+    "@aetheros/runner": "0.1.1",
+    "@aetheros/control-room": "0.1.1",
+    "@aetheros/voice": "0.1.1",
+    "@aetheros/workspace": "0.1.1",
+    "@aetheros/models": "0.1.1",
+    "@aetheros/provider-google": "0.1.1",
+    "@aetheros/provider-openai-compatible": "0.1.1"
+  },
+  "files": [
+    "src",
+    "dist",
+    "bin",
+    "templates",
+    "kits",
+    "README.md"
+  ]
+}

package/src/machine.js

@@ -0,0 +1,41 @@
+import {execFileSync} from 'node:child_process';
+import {checkMachine} from './setup.js';
+
+/** Install commands per platform. Linux is listed only (package managers and sudo differ), never run automatically. */
+const PLANS = {
+  win32: {git: ['winget', ['install', '-e', '--id', 'Git.Git']], gh: ['winget', ['install', '-e', '--id', 'GitHub.cli']], code: ['winget', ['install', '-e', '--id', 'Microsoft.VisualStudioCode']], node: ['winget', ['install', '-e', '--id', 'OpenJS.NodeJS.LTS']]},
+  darwin: {git: ['brew', ['install', 'git']], gh: ['brew', ['install', 'gh']], code: ['brew', ['install', '--cask', 'visual-studio-code']], node: ['brew', ['install', 'node']]},
+  linux: {git: ['sudo', ['apt-get', 'install', '-y', 'git']], gh: ['sudo', ['apt-get', 'install', '-y', 'gh']], code: ['sudo', ['snap', 'install', 'code', '--classic']], node: ['sudo', ['apt-get', 'install', '-y', 'nodejs']]}
+};
+const CLAUDE = ['npm', ['install', '-g', '@anthropic-ai/claude-code']];
+const EXTENSION = ['code', ['--install-extension', 'anthropic.claude-code']];
+
+export function machinePlan({platform = process.platform, check = checkMachine()} = {}) {
+  const table = PLANS[platform] ?? {};
+  const steps = [];
+  for (const r of check.results) {
+    if (r.ok || r.name === 'npm') continue;
+    const cmd = r.name === 'claude' ? CLAUDE : table[r.name];
+    if (cmd) steps.push({tool: r.name, command: cmd[0], args: cmd[1], required: r.required});
+  }
+  const codeReady = check.results.find(r => r.name === 'code')?.ok || steps.some(s => s.tool === 'code');
+  if (codeReady) steps.push({tool: 'claude-code-extension', command: EXTENSION[0], args: EXTENSION[1], required: false});
+  return {platform, automatic: platform === 'win32' || platform === 'darwin', steps};
+}
+
+/** Show the plan; with install: true run each step after asking (or all with yes: true). Never runs on Linux. */
+export async function setupMachine({install = false, yes = false, ask, log, platform, check, run = (cmd, args) => execFileSync(cmd, args, {stdio: 'inherit', shell: process.platform === 'win32'})} = {}) {
+  const plan = machinePlan({platform, check});
+  if (!plan.steps.length) { log('Nothing to install: this computer has every tool AetherOS uses.'); return {plan, ran: []}; }
+  for (const s of plan.steps) log(`${s.required ? 'needed  ' : 'optional'} ${s.tool}: ${s.command} ${s.args.join(' ')}`);
+  if (!install) { log('Preview only. Run `aether setup machine --install` to install (you will be asked for each).'); return {plan, ran: []}; }
+  if (!plan.automatic) { log('Automatic install is only offered on Windows and macOS; run the commands above yourself.'); return {plan, ran: []}; }
+  const ran = [];
+  for (const s of plan.steps) {
+    if (!yes && !String(await ask(`Install ${s.tool}? [y/N] `)).trim().toLowerCase().startsWith('y')) continue;
+    run(s.command, s.args);
+    ran.push(s.tool);
+  }
+  log(ran.length ? `Installed: ${ran.join(', ')}. Open a new terminal, then run \`aether doctor machine\`.` : 'Nothing installed.');
+  return {plan, ran};
+}

package/src/setup.js

@@ -0,0 +1,100 @@
+import {execFileSync} from 'node:child_process';
+import {existsSync, readFileSync, writeFileSync} from 'node:fs';
+import {readBrand, writeBrand} from '@aetheros/workflow';
+import {basename, resolve} from 'node:path';
+import {createInterface} from 'node:readline/promises';
+
+const KIT_ORDER = ['github', 'memory', 'claude', 'openai', 'githooks', 'mcp'];
+const ABOUT = {
+  github: 'GitHub issue and pull request templates',
+  memory: 'Handover, roadmap, feature folders, workflow settings',
+  claude: 'Claude Code agents, skills and guard hooks',
+  openai: 'AGENTS.md for OpenAI tooling',
+  githooks: 'Git hooks guard rails for every tool and person',
+  mcp: 'Claude Code MCP servers (Playwright browser)'
+};
+const isGitRepo = root => { try { execFileSync('git', ['rev-parse', '--git-dir'], {cwd: root, stdio: 'ignore'}); return true; } catch { return false; } };
+
+/**
+ * Guided project setup. Non-interactive with --yes (defaults) or --kits a,b,c; otherwise asks one question per kit.
+ * installers: {kit: (root, {dryRun}) => {created, skipped}}. Never overwrites existing files.
+ */
+export async function setup(args, cwd, log, {installers, ask, interactive = Boolean(process.stdin.isTTY)} = {}) {
+  const root = resolve(cwd);
+  const dryRun = args.includes('--dry-run');
+  const git = isGitRepo(root);
+  const defaults = KIT_ORDER.filter(k => k !== 'mcp' && (k !== 'githooks' || git));
+  const listed = args.includes('--kits') ? (args[args.indexOf('--kits') + 1] || '').split(',').map(s => s.trim()).filter(Boolean) : null;
+  if (listed && listed.some(k => !installers[k])) throw new Error('Unknown kit in --kits; available: ' + KIT_ORDER.join(', '));
+  if (listed?.includes('githooks') && !git) throw new Error('githooks needs a git repository (run git init first)');
+  let kits = listed ?? defaults;
+  if (!listed && !args.includes('--yes') && interactive) {
+    const rl = ask ? null : createInterface({input: process.stdin, output: process.stdout});
+    const question = ask ?? (q => rl.question(q));
+    kits = [];
+    try {
+      for (const kit of KIT_ORDER) {
+        if (kit === 'githooks' && !git) continue;
+        const def = defaults.includes(kit);
+        const answer = String(await question(`Install ${kit} (${ABOUT[kit]})? ${def ? '[Y/n]' : '[y/N]'} `)).trim().toLowerCase();
+        if (answer ? answer.startsWith('y') : def) kits.push(kit);
+      }
+    } finally { rl?.close(); }
+  }
+  // Brand: the product's OS name, assistant name and accent colour (e.g. "Nova OS", "Nova").
+  const flag = name => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+  let brand = readBrand(root);
+  let osName = flag('--os-name'), assistantName = flag('--assistant'), accent = flag('--accent');
+  if (!brand && !osName && !args.includes('--yes') && interactive) {
+    const rl = ask ? null : createInterface({input: process.stdin, output: process.stdout});
+    const question = ask ?? (q => rl.question(q));
+    try {
+      osName = String(await question(`What is your OS called? [${basename(root)} OS] `)).trim() || `${basename(root)} OS`;
+      assistantName = String(await question('What is your assistant called? [Aevron] ')).trim() || 'Aevron';
+      accent = String(await question('Accent colour (#rrggbb, empty for default)? ')).trim() || undefined;
+    } finally { rl?.close(); }
+  }
+  if (osName || assistantName) {
+    const next = {osName: osName || brand?.osName || `${basename(root)} OS`, assistantName: assistantName || brand?.assistantName || 'Aevron', theme: {...(brand?.theme ?? {}), ...(accent && {accent})}};
+    if (!dryRun) brand = writeBrand(root, next);
+    log(`${dryRun ? 'would brand' : 'branded'}: ${next.osName} · assistant ${next.assistantName}`);
+  }
+  const hadClaudeMd = existsSync(resolve(root, 'CLAUDE.md'));
+  const config = resolve(root, 'aether.config.json');
+  if (!existsSync(config)) {
+    if (!dryRun) writeFileSync(config, JSON.stringify({schemaVersion: 1, project: {name: basename(root)}, providers: ['claude', 'openai'], approval: 'writes'}, null, 2) + '\n', {flag: 'wx'});
+    log((dryRun ? 'would create ' : 'created ') + 'aether.config.json');
+  }
+  for (const kit of kits) {
+    const {created, skipped} = installers[kit](root, {dryRun});
+    log(`${kit}: ${created.length} ${dryRun ? 'to create' : 'created'}, ${skipped.length} kept`);
+  }
+  if (brand && !dryRun && !hadClaudeMd && existsSync(resolve(root, 'CLAUDE.md'))) {
+    const file = resolve(root, 'CLAUDE.md');
+    writeFileSync(file, readFileSync(file, 'utf8').replace(/^# Project instructions/m, `# ${brand.osName} — project instructions\n\nThe AI assistant for this project is called ${brand.assistantName}.`));
+  }
+  log('Next: `aether doctor machine` (tools on this computer), `aether check`, `aether room`, `aether run init packs/<app>`.');
+  return kits;
+}
+
+const TOOLS = [
+  {name: 'node', args: ['--version'], required: true, min: 20, hint: 'https://nodejs.org (version 20 or newer)'},
+  {name: 'git', args: ['--version'], required: true, hint: 'https://git-scm.com'},
+  {name: 'npm', args: ['--version'], required: true, hint: 'comes with Node.js'},
+  {name: 'gh', args: ['--version'], hint: 'https://cli.github.com (GitHub from the terminal)'},
+  {name: 'claude', args: ['--version'], hint: 'https://claude.com/claude-code (Claude Code CLI)'},
+  {name: 'code', args: ['--version'], hint: 'https://code.visualstudio.com (for the Control Room panel)'}
+];
+
+/** Check the tools AetherOS uses on this computer. Never installs anything. */
+export function checkMachine({run = (cmd, args) => execFileSync(cmd, args, {encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000, shell: process.platform === 'win32'}), nodeVersion = process.versions.node} = {}) {
+  const results = TOOLS.map(tool => {
+    try {
+      const out = tool.name === 'node' ? 'v' + nodeVersion : run(tool.name, tool.args);
+      const version = (/\d+\.\d+(\.\d+)?/.exec(out) || [''])[0];
+      const tooOld = tool.min && Number(version.split('.')[0]) < tool.min;
+      return {name: tool.name, ok: !tooOld, required: Boolean(tool.required), version, hint: tooOld ? tool.hint : undefined};
+    } catch { return {name: tool.name, ok: false, required: Boolean(tool.required), hint: tool.hint}; }
+  });
+  return {ok: results.every(r => r.ok || !r.required), results};
+}

package/src/sprint.js

@@ -0,0 +1,31 @@
+import {closeSprint, githubClient, planSprint, repoFromGit, sprintStatus} from '@aetheros/workflow';
+
+const value = (args, name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+
+/** aether sprint status | plan --title "Sprint N — goal" --issues 1,2 [--due YYYY-MM-DD] | close [--next <milestone>] */
+export async function runSprint(args, cwd, log, {token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN, fetchImpl} = {}) {
+  const sub = args[0] || 'status';
+  const repo = value(args, '--repo') || repoFromGit(cwd);
+  if (!repo) throw new Error('Could not find the GitHub repository; pass --repo owner/name');
+  const client = githubClient({token, fetchImpl});
+  if (sub === 'status') {
+    const s = await sprintStatus(client, repo);
+    if (!s) { log('No open sprint. Plan one with: aether sprint plan --title "Sprint 1 — goal" --issues 1,2,3'); return; }
+    log(`${s.title}${s.dueOn ? ' (due ' + s.dueOn.slice(0, 10) + ')' : ''}: ${s.points.done} points done, ${s.points.open} open`);
+    for (const i of s.open) log(`  #${i.number} ${i.title}${i.points ? ` [${i.points}]` : ''}${i.blocked ? ' — waiting on the owner' : ''}`);
+    return;
+  }
+  if (sub === 'plan') {
+    const issues = (value(args, '--issues') || '').split(',').map(n => Number(n.trim().replace(/^#/, ''))).filter(Boolean);
+    const r = await planSprint(client, repo, {title: value(args, '--title'), dueOn: value(args, '--due'), issues});
+    log(`created ${r.title} (milestone ${r.number}) with ${r.issues.length} issue(s), ${r.points} points`);
+    return;
+  }
+  if (sub === 'close') {
+    const next = value(args, '--next');
+    const r = await closeSprint(client, repo, {next: next ? Number(next) : undefined});
+    log(`closed ${r.title}: ${r.points.done} points done; moved ${r.moved.length} open issue(s) to ${r.movedTo === 'backlog' ? 'the backlog' : 'milestone ' + r.movedTo}`);
+    return;
+  }
+  throw new Error('Usage: aether sprint <status|plan --title "Sprint N — goal" --issues 1,2 [--due YYYY-MM-DD]|close [--next <milestone number>]> [--repo owner/name]');
+}

package/src/start.js

@@ -0,0 +1,176 @@
+// `aether start`: one command (or a double-click on start-aetheros.cmd) that starts everything and opens it.
+// First run: asks for an AI provider key and saves it outside the project (in the home folder, owner-only).
+// Every run: starts the workspace and the voice console, then opens both in the browser.
+// Already running: opens the pages again and exits.
+import {spawn} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import {chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {basename, join} from 'node:path';
+import {createInterface} from 'node:readline';
+import {fileURLToPath} from 'node:url';
+
+export const PROVIDER_KEYS = [
+  {env: 'ANTHROPIC_API_KEY', name: 'Anthropic (Claude)', hint: 'sk-ant-…, from console.anthropic.com (create it inside a workspace)'},
+  {env: 'OPENAI_API_KEY', name: 'OpenAI', hint: 'sk-…, from platform.openai.com'},
+  {env: 'GEMINI_API_KEY', name: 'Google Gemini', hint: 'from aistudio.google.com'},
+];
+const ALL_KEYS = [...PROVIDER_KEYS.map(p => p.env), 'GOOGLE_API_KEY', 'XAI_API_KEY', 'MISTRAL_API_KEY'];
+const STATE = join('.aether', 'local', 'start.json');
+
+export const LAUNCHERS = {
+  'start-aetheros.cmd': '@echo off\r\nREM Starts AetherOS for this project and opens it in the browser. Double-click or run: start-aetheros\r\ncd /d "%~dp0"\r\nnode .aether\\aether.mjs start %*\r\nif errorlevel 1 pause\r\n',
+  'start-aetheros.sh': '#!/bin/sh\n# Starts AetherOS for this project and opens it in the browser. Run: ./start-aetheros.sh\ncd "$(dirname "$0")" && exec node .aether/aether.mjs start "$@"\n',
+};
+
+/** Where this project's settings live: the home folder, never the project (keys must not reach git). */
+export function settingsFile(root, home = homedir()) {
+  let real = root;
+  try { real = realpathSync(root); } catch {}
+  const id = createHash('sha256').update(real.toLowerCase()).digest('hex').slice(0, 10);
+  return join(home, '.aether', 'projects', `${basename(real).replace(/[^\w.-]/g, '_')}-${id}.json`);
+}
+
+export function loadSettings(file) {
+  try { const s = JSON.parse(readFileSync(file, 'utf8')); return s && typeof s.env === 'object' ? s : {env: {}}; } catch { return {env: {}}; }
+}
+
+export function saveSettings(file, settings) {
+  mkdirSync(join(file, '..'), {recursive: true, mode: 0o700});
+  writeFileSync(file, JSON.stringify({schemaVersion: 1, ...settings}, null, 2) + '\n', {mode: 0o600});
+  try { chmodSync(file, 0o600); } catch {}
+}
+
+/** Writes the double-click launchers into the project when they're missing. Returns the names written. */
+export function writeLaunchers(root) {
+  const written = [];
+  for (const [name, text] of Object.entries(LAUNCHERS)) {
+    const file = join(root, name);
+    if (existsSync(file)) continue;
+    writeFileSync(file, text, {mode: 0o755});
+    written.push(name);
+  }
+  return written;
+}
+
+/** The keys to start with: the terminal's own variables win, then the saved ones. */
+export function resolveKeys(env, settings) {
+  const keys = {};
+  for (const name of ALL_KEYS) {
+    if (env[name]) keys[name] = env[name];
+    else if (settings.env?.[name]) keys[name] = settings.env[name];
+  }
+  return keys;
+}
+
+/** Asks for one key, Anthropic first; the typed key is not shown on screen. */
+export async function askForKey(ask, log) {
+  log('\nAetherOS needs one AI provider key so your agents can answer. It is saved in your home folder, never in the project.');
+  for (const p of PROVIDER_KEYS) {
+    const key = String(await ask(`Paste your ${p.name} API key (${p.hint}), or press Enter to skip: `, {secret: true})).trim();
+    if (key) return {[p.env]: key};
+  }
+  return {};
+}
+
+function terminalAsk() {
+  return (question, {secret} = {}) => new Promise(resolveAnswer => {
+    const rl = createInterface({input: process.stdin, output: process.stdout, terminal: true});
+    if (secret) {
+      const write = rl._writeToOutput?.bind(rl);
+      rl._writeToOutput = text => { if (text.startsWith(question)) write?.(text); else if (!/^\r?\n$/.test(text)) write?.('*'); else write?.(text); };
+    }
+    rl.question(question, answer => { rl.close(); if (secret) process.stdout.write('\n'); resolveAnswer(answer); });
+  });
+}
+
+export function openInBrowser(url, {spawnImpl = spawn, platform = process.platform} = {}) {
+  const [cmd, args] = platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+  try { spawnImpl(cmd, args, {stdio: 'ignore', detached: true}).unref?.(); return true; } catch { return false; }
+}
+
+async function answers(url, fetchImpl) {
+  try { return (await fetchImpl(url, {signal: AbortSignal.timeout(1500)})).status < 500; } catch { return false; }
+}
+
+/** Starts a child `aether <args>` and resolves with the first http URL it prints after `label`. */
+function startChild(cliPath, args, {root, env, label, log, spawnImpl}) {
+  return new Promise((resolveUrl, reject) => {
+    const child = spawnImpl(process.execPath, [cliPath, ...args], {cwd: root, env, stdio: ['ignore', 'pipe', 'pipe']});
+    let found = false, buffer = '';
+    const onData = chunk => {
+      buffer += chunk;
+      const lines = buffer.split(/\r?\n/);
+      buffer = lines.pop();
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        if (!found) {
+          const match = line.includes(label) && line.match(/https?:\/\/127\.0\.0\.1:\d+\/\S*/);
+          if (match) { found = true; resolveUrl({child, url: match[0]}); continue; }
+        }
+        log(`  [${args[0]}] ${line}`);
+      }
+    };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    child.on('exit', code => { if (!found) reject(new Error(`aether ${args[0]} stopped (exit ${code}) before it was ready`)); });
+  });
+}
+
+export async function start(args, root, {log = console.log, env = process.env, home = homedir(), ask, interactive = Boolean(process.stdin.isTTY), cliPath, open = openInBrowser, spawnImpl = spawn, fetchImpl = fetch, wait = true} = {}) {
+  if (!existsSync(join(root, '.aether')) && !existsSync(join(root, 'aether.config.json'))) {
+    throw new Error('AetherOS is not set up in this folder yet. Run:  npx @aetheros/create');
+  }
+  for (const name of writeLaunchers(root)) log(`created ${name} (double-click it, or run it, to start AetherOS next time)`);
+  if (args.includes('--launchers')) return {launchersOnly: true};
+
+  const file = settingsFile(root, home);
+  const settings = loadSettings(file);
+  if (args.includes('--where')) { log(file); return {file}; }
+  let keys = resolveKeys(env, args.includes('--reset') ? {env: {}} : settings);
+  if (!Object.keys(keys).length || args.includes('--reset')) {
+    if (interactive) {
+      const typed = await askForKey(ask ?? terminalAsk(), log);
+      if (Object.keys(typed).length) {
+        saveSettings(file, {...settings, env: {...(args.includes('--reset') ? {} : settings.env), ...typed}});
+        log(`Saved in ${file} (only your user can read it; delete the file to forget the key).`);
+        keys = {...keys, ...typed};
+      }
+    }
+    if (!Object.keys(keys).length) log('No AI provider key: the pages open, but agents can only answer once you add one. Run  node .aether/aether.mjs start --reset  to add it.');
+  }
+
+  const noOpen = args.includes('--no-open') || env.AETHER_NO_OPEN === '1';
+  const statePath = join(root, STATE);
+  let state = {};
+  try { state = JSON.parse(readFileSync(statePath, 'utf8')); } catch {}
+  if (state.workspace && await answers(state.workspace, fetchImpl)) {
+    log(`AetherOS is already running.\n  Workspace:      ${state.workspace}\n  Voice console:  ${state.voice ?? '(not running)'}`);
+    if (!noOpen) { open(state.workspace); if (state.voice) open(state.voice); }
+    return {alreadyRunning: true, ...state};
+  }
+
+  const childEnv = {...env, ...keys};
+  const cli = cliPath ?? fileURLToPath(new URL('../bin/aether.js', import.meta.url));
+  log('Starting AetherOS…');
+  const workspace = await startChild(cli, ['workspace', '--port', String(Number(value(args, '--port') ?? 4850))], {root, env: childEnv, label: 'Workspace:', log, spawnImpl});
+  let voice;
+  if (!args.includes('--no-voice')) {
+    try { voice = await startChild(cli, ['voice', '--agents', '--port', String(Number(value(args, '--voice-port') ?? 4747))], {root, env: childEnv, label: 'Voice console:', log, spawnImpl}); }
+    catch (error) { log(`Voice console not started: ${error.message}`); }
+  }
+  mkdirSync(join(root, '.aether', 'local'), {recursive: true});
+  writeFileSync(statePath, JSON.stringify({workspace: workspace.url, ...(voice && {voice: voice.url}), startedAt: new Date().toISOString()}, null, 2) + '\n');
+  log(`\nAetherOS is running.\n  Workspace:      ${workspace.url}\n  Voice console:  ${voice?.url ?? '(not started)'}  (Chrome or Edge, allow the microphone)\nPress Ctrl+C here to stop.`);
+  if (!noOpen) { open(workspace.url); if (voice) open(voice.url); }
+  const children = [workspace.child, voice?.child].filter(Boolean);
+  const stop = () => { for (const c of children) try { c.kill(); } catch {} };
+  if (!wait) return {workspace: workspace.url, voice: voice?.url, stop};
+  process.on('SIGINT', () => { stop(); process.exit(0); });
+  process.on('SIGTERM', () => { stop(); process.exit(0); });
+  await new Promise(resolveDone => workspace.child.on('exit', resolveDone));
+  stop();
+  return {workspace: workspace.url, voice: voice?.url};
+}
+
+function value(args, name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.