@adityaaria/agent-os 1.0.0

package/scripts/run-step.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { deriveRunStatus, renderReport } from './lib/run-utils.mjs';
+import { createCli, fail, failAll, showHelp, wantsHelp } from './lib/cli-utils.mjs';
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'run-step',
+    description: 'Update step state inside a run directory',
+    usage: ['agent-os run-step --run-dir <dir> --step <number> --status <status> [options]'],
+    required: [
+      { flag: '--run-dir <dir>', desc: 'Path to the run directory' },
+      { flag: '--step <number>', desc: 'Step number to update' },
+      { flag: '--status <status>', desc: 'New status: pending|running|passed|failed|blocked' }
+    ],
+    options: [
+      { flag: '--notify-channel-config <file>', desc: 'Channel config for lifecycle notifications' },
+      { flag: '--notify-channel <name>', desc: 'Channel name for notifications' },
+      { flag: '--notify-on <events>', desc: 'Comma-separated lifecycle events to notify on' },
+      { flag: '--dry-run-notify', desc: 'Write notification payload to file' },
+      { flag: '--send-notify', desc: 'Send notification via configured channel' }
+    ],
+    examples: [
+      'agent-os run-step --run-dir .agent-os/runs/my-run --step 1 --status running',
+      'agent-os run-step --run-dir .agent-os/runs/my-run --step 1 --status failed --notify-channel-config .agent-os/project/report-channels.json --notify-channel telegram --notify-on failed,blocked --dry-run-notify'
+    ]
+  });
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const repoRoot = path.resolve(path.dirname(__filename), '..');
+
+const { hasFlag, takeOption } = createCli(process.argv.slice(2));
+const allowedStatuses = new Set(['pending', 'running', 'passed', 'failed', 'blocked']);
+
+const runDir = takeOption('--run-dir');
+const stepNumber = Number(takeOption('--step'));
+const status = takeOption('--status');
+const notifyChannelConfig = takeOption('--notify-channel-config');
+const notifyChannel = takeOption('--notify-channel');
+const notifyOn = takeOption('--notify-on');
+const dryRunNotify = hasFlag('--dry-run-notify');
+const sendNotify = hasFlag('--send-notify');
+
+const errors = [];
+if (!runDir) errors.push('Missing --run-dir <dir>.');
+if (!Number.isInteger(stepNumber)) errors.push('Missing or invalid --step <number>.');
+if (!status) errors.push('Missing --status <pending|running|passed|failed|blocked>.');
+if (status && !allowedStatuses.has(status)) errors.push(`Invalid status: ${status}. Expected: pending|running|passed|failed|blocked.`);
+failAll(errors, 'agent-os run-step --run-dir .agent-os/runs/my-run --step 1 --status running', 'run-step');
+
+if ((dryRunNotify && sendNotify) || ((notifyChannelConfig || notifyChannel || notifyOn) && !dryRunNotify && !sendNotify)) {
+  fail('Use either --dry-run-notify or --send-notify for lifecycle notifications.');
+}
+
+if ((dryRunNotify || sendNotify) && (!notifyChannelConfig || !notifyChannel || !notifyOn)) {
+  fail('Lifecycle notifications require --notify-channel-config, --notify-channel, and --notify-on.');
+}
+
+const absoluteRunDir = path.resolve(process.cwd(), runDir);
+const planPath = path.join(absoluteRunDir, 'plan.json');
+const stepsPath = path.join(absoluteRunDir, 'steps.json');
+const reportPath = path.join(absoluteRunDir, 'master-report.md');
+
+if (!fs.existsSync(planPath) || !fs.existsSync(stepsPath)) {
+  fail(`Run directory is missing plan.json or steps.json: ${absoluteRunDir}`);
+}
+
+const plan = JSON.parse(fs.readFileSync(planPath, 'utf8'));
+const steps = JSON.parse(fs.readFileSync(stepsPath, 'utf8'));
+const targetStep = steps.find((step) => step.step === stepNumber);
+
+if (!targetStep) {
+  fail(`Step not found: ${stepNumber}`);
+}
+
+if (targetStep.status === 'blocked' && status !== 'blocked') {
+  fail(`Step ${stepNumber} is blocked`);
+}
+
+if (status === 'running' || status === 'passed') {
+  const incompleteDependencies = targetStep.dependsOn.filter((dependencySkill) => {
+    const dependencyStep = steps.find((step) => step.skill === dependencySkill);
+    return !dependencyStep || dependencyStep.status !== 'passed';
+  });
+
+  if (incompleteDependencies.length > 0) {
+    fail(`Dependencies must pass before step ${stepNumber} can run: ${incompleteDependencies.join(', ')}`);
+  }
+}
+
+targetStep.status = status;
+if (status === 'failed') {
+  const blockedSkills = new Set([targetStep.skill]);
+  let changed = true;
+
+  while (changed) {
+    changed = false;
+    for (const step of steps) {
+      if (step.status === 'failed') {
+        blockedSkills.add(step.skill);
+      }
+      if (step.step !== targetStep.step && step.dependsOn.some((skill) => blockedSkills.has(skill))) {
+        if (step.status !== 'blocked') {
+          step.status = 'blocked';
+          changed = true;
+        }
+        blockedSkills.add(step.skill);
+      }
+    }
+  }
+}
+plan.executionPlan = plan.executionPlan.map((step) => (
+  steps.find((updatedStep) => updatedStep.step === step.step) ?? step
+));
+
+fs.writeFileSync(stepsPath, JSON.stringify(steps, null, 2) + '\n');
+fs.writeFileSync(planPath, JSON.stringify(plan, null, 2) + '\n');
+fs.writeFileSync(reportPath, renderReport(plan));
+
+const notification = maybeNotifyLifecycle();
+
+function maybeNotifyLifecycle() {
+  if (!dryRunNotify && !sendNotify) return null;
+
+  const notifyEvents = new Set(notifyOn.split(',').map((event) => event.trim()).filter(Boolean));
+  const runStatus = deriveRunStatus(steps);
+  const actualEvents = new Set([status, runStatus]);
+  if (steps.some((step) => step.status === 'blocked')) actualEvents.add('blocked');
+  if (steps.some((step) => step.status === 'failed')) actualEvents.add('failed');
+
+  const matchedEvent = [status, runStatus, 'failed', 'blocked', 'complete']
+    .find((event) => actualEvents.has(event) && notifyEvents.has(event));
+
+  if (!matchedEvent) {
+    return { skipped: true, reason: 'No matching lifecycle event.' };
+  }
+
+  const notifyArgs = [
+    path.join(repoRoot, 'scripts', 'report-notify.mjs'),
+    '--run-dir',
+    absoluteRunDir,
+    '--channel-config',
+    notifyChannelConfig,
+    '--channel',
+    notifyChannel,
+    '--event',
+    matchedEvent,
+    dryRunNotify ? '--dry-run' : '--send'
+  ];
+
+  const result = spawnSync(process.execPath, notifyArgs, {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    env: process.env
+  });
+
+  if (result.status !== 0) {
+    if (result.stdout) process.stdout.write(result.stdout);
+    fail(result.stderr || `Lifecycle notification failed for channel: ${notifyChannel}`);
+  }
+
+  if (result.stdout) process.stdout.write(result.stdout);
+  return { channel: notifyChannel, mode: dryRunNotify ? 'dry-run' : 'send' };
+}
+
+if (notification?.channel) {
+  console.log(`Notification: ${notification.channel} (${notification.mode})`);
+}
+console.log(JSON.stringify({ runDir: absoluteRunDir, step: stepNumber, status }, null, 2));

package/scripts/setup-wizard.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { wantsHelp, showHelp } from './lib/cli-utils.mjs';
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'setup',
+    description: 'Quick setup wizard for new Agent OS installations',
+    usage: ['agent-os setup'],
+    examples: [
+      'agent-os setup',
+      'cd /path/to/your/project && agent-os setup'
+    ]
+  });
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const repoRoot = path.resolve(path.dirname(__filename), '..');
+
+function log(message) {
+  console.log(`  ${message}`);
+}
+
+function findWorkspaceFile(startDir, maxLevels = 2) {
+  let dir = startDir;
+  for (let i = 0; i <= maxLevels; i++) {
+    const entries = fs.readdirSync(dir).filter((f) => f.endsWith('.code-workspace'));
+    if (entries.length > 0) {
+      return path.join(dir, entries[0]);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function detectProjectType(dir) {
+  const manifests = [
+    { file: 'package.json', type: 'Node.js' },
+    { file: 'requirements.txt', type: 'Python' },
+    { file: 'Cargo.toml', type: 'Rust' },
+    { file: 'go.mod', type: 'Go' },
+    { file: 'pom.xml', type: 'Java (Maven)' },
+    { file: 'composer.json', type: 'PHP (Composer)' },
+    { file: 'Gemfile', type: 'Ruby' },
+    { file: 'pubspec.yaml', type: 'Dart/Flutter' }
+  ];
+
+  for (const manifest of manifests) {
+    if (fs.existsSync(path.join(dir, manifest.file))) {
+      return manifest.type;
+    }
+  }
+  return 'Unknown';
+}
+
+function generateWorkspaceFile(dir) {
+  const workspaceContent = JSON.stringify({
+    folders: [{ path: '.' }]
+  }, null, 2) + '\n';
+
+  const dirName = path.basename(dir);
+  const workspacePath = path.join(dir, `${dirName}.code-workspace`);
+  fs.writeFileSync(workspacePath, workspaceContent);
+  return workspacePath;
+}
+
+console.log('\n=== Agent OS Setup Wizard ===\n');
+
+const cwd = process.cwd();
+
+// Step 1: Find or create workspace file
+let workspacePath = findWorkspaceFile(cwd);
+
+if (workspacePath) {
+  log(`✓ Found existing workspace file: ${workspacePath}`);
+} else {
+  const projectType = detectProjectType(cwd);
+  log(`Detected project type: ${projectType}`);
+  workspacePath = generateWorkspaceFile(cwd);
+  log(`✓ Generated .code-workspace for ${projectType} project`);
+}
+
+// Step 2: Run installer
+log('');
+log('Running Agent OS installer...');
+log('');
+
+const installerPath = path.join(repoRoot, 'scripts', 'install.mjs');
+const result = spawnSync(process.execPath, [
+  installerPath,
+  '--workspace-file', workspacePath,
+  '--all',
+  '--backup'
+], {
+  cwd: repoRoot,
+  stdio: 'inherit'
+});
+
+if (result.status !== 0) {
+  console.error('\n✗ ERROR [setup]: Installation failed.');
+  console.error('  → Suggestion: Check the output above for details and try running the installer manually.');
+  process.exit(1);
+}
+
+// Step 3: Print summary
+console.log('\n=== Setup Complete ===\n');
+log('✓ Agent OS installed successfully');
+log('');
+log('Next step: Open your IDE and trigger:');
+log('  ANALYZE PROJECT: We are using [your framework] frontend and [your framework] backend.');
+log('');

package/scripts/sync-runtime.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { wantsHelp, showHelp } from './lib/cli-utils.mjs';
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'sync',
+    description: 'Sync framework source into the local .agent-os runtime',
+    usage: ['agent-os sync [--target <dir>]'],
+    options: [
+      { flag: '--target <dir>', desc: 'Target directory', default: '.' }
+    ],
+    examples: [
+      'agent-os sync',
+      'agent-os sync --target /path/to/project'
+    ]
+  });
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const repoRoot = path.resolve(path.dirname(__filename), '..');
+const args = process.argv.slice(2);
+
+function getArg(name, fallback = null) {
+  const index = args.indexOf(name);
+  if (index === -1) return fallback;
+  return args[index + 1] ?? fallback;
+}
+
+const targetRoot = path.resolve(process.cwd(), getArg('--target', '.'));
+const runtimeRoot = path.join(targetRoot, '.agent-os');
+
+function copyRecursive(source, destination) {
+  if (!fs.existsSync(source)) return;
+
+  const stat = fs.statSync(source);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(destination, { recursive: true });
+    for (const entry of fs.readdirSync(source)) {
+      copyRecursive(path.join(source, entry), path.join(destination, entry));
+    }
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
+}
+
+for (const file of ['AGENTS.md', 'ENTRYPOINT.md', 'AGENT_OS_BOOTSTRAP.md', 'plugin.json']) {
+  copyRecursive(path.join(repoRoot, file), path.join(runtimeRoot, file));
+}
+
+for (const directory of ['core', 'skills', 'templates', 'hooks']) {
+  copyRecursive(path.join(repoRoot, directory), path.join(runtimeRoot, directory));
+}
+
+copyRecursive(path.join(repoRoot, 'validators'), path.join(runtimeRoot, 'validators'));
+
+const projectRoot = path.join(runtimeRoot, 'project');
+fs.mkdirSync(projectRoot, { recursive: true });
+
+for (const file of ['PROJECT_PROFILE.md', 'TECH_STACK.md', 'ARCHITECTURE.md']) {
+  const destination = path.join(projectRoot, file);
+  if (!fs.existsSync(destination)) {
+    copyRecursive(path.join(repoRoot, 'templates', file), destination);
+  }
+}
+
+const workspaceMap = path.join(projectRoot, 'WORKSPACE_MAP.md');
+if (!fs.existsSync(workspaceMap)) {
+  fs.writeFileSync(workspaceMap, [
+    '# Agent OS Workspace Map',
+    '',
+    '- **Workspace Name**: local-runtime',
+    '- **Workspace File**: N/A. Reason: Runtime synced in repository mode.',
+    '- **Install Root**: N/A. Reason: Generated by sync-runtime.',
+    '',
+    '## Detected Folders',
+    '',
+    'N/A. Reason: Runtime sync does not inspect external workspace folders.',
+    ''
+  ].join('\n'));
+}
+
+console.log(`Runtime synced: ${runtimeRoot}`);

package/scripts/telegram-bot.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { assertEnabledChannel, loadReportChannel } from './lib/run-utils.mjs';
+import {
+  createTelegramAccessControl,
+  processTelegramUpdates,
+  readTelegramUpdatesFromFile,
+  writeTelegramBotOutput
+} from './lib/telegram-bot-utils.mjs';
+import { createCli, fail, failAll, resolveDefault, showHelp, wantsHelp } from './lib/cli-utils.mjs';
+
+const { hasFlag, takeOption } = createCli(process.argv.slice(2));
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'telegram-bot',
+    description: 'Process Telegram bot updates from a file (dry-run)',
+    usage: [
+      'agent-os telegram-bot --updates-file <file> --dry-run [options]'
+    ],
+    required: [
+      { flag: '--updates-file <file>', desc: 'Path to Telegram updates JSON file' },
+      { flag: '--allowed-chat-id <ids>', desc: 'Comma-separated allowed Telegram chat IDs' },
+      { flag: '--dry-run', desc: 'Write responses to file (no API calls)' }
+    ],
+    options: [
+      { flag: '--channel-config <file>', desc: 'Channel config file', default: '.agent-os/project/report-channels.json' },
+      { flag: '--channel <name>', desc: 'Channel name', default: 'telegram' },
+      { flag: '--run-root <dir>', desc: 'Run directory root', default: '.agent-os/runs' },
+      { flag: '--output <file>', desc: 'Override output path' }
+    ],
+    examples: [
+      'agent-os telegram-bot --updates-file updates.json --allowed-chat-id 12345 --dry-run',
+      'agent-os telegram-bot --updates-file updates.json --allowed-chat-id 12345 --dry-run --run-root .agent-os/runs'
+    ]
+  });
+}
+
+const updatesFile = takeOption('--updates-file');
+const channelConfig = takeOption('--channel-config') ?? resolveDefault(null, '.agent-os/project/report-channels.json');
+const channelName = takeOption('--channel') ?? 'telegram';
+const allowedChatId = takeOption('--allowed-chat-id');
+const runRoot = takeOption('--run-root') ?? resolveDefault(null, '.agent-os/runs');
+const outputOverride = takeOption('--output');
+const dryRun = hasFlag('--dry-run');
+
+if (!dryRun) {
+  fail('telegram-bot currently supports --dry-run only.');
+}
+
+const errors = [];
+if (!updatesFile) errors.push('Missing --updates-file <file>.');
+if (!channelConfig) errors.push('Missing --channel-config <file> (no default found at .agent-os/project/report-channels.json).');
+if (!allowedChatId) errors.push('Missing --allowed-chat-id <id[,id]> (required, no default).');
+if (!runRoot) errors.push('Missing --run-root <dir> (no default found at .agent-os/runs).');
+failAll(errors, 'agent-os telegram-bot --updates-file updates.json --allowed-chat-id 12345 --dry-run', 'telegram-bot');
+
+let channelContext;
+try {
+  channelContext = loadReportChannel(channelConfig, channelName);
+  assertEnabledChannel(channelContext);
+} catch (err) {
+  fail(err.message);
+}
+
+if (channelContext.channel.type !== 'telegram') {
+  fail(`Report channel is not a telegram channel: ${channelName}`);
+}
+
+const updates = readTelegramUpdatesFromFile(updatesFile);
+const responses = processTelegramUpdates({
+  updates,
+  accessControl: createTelegramAccessControl({
+    allowedChatId,
+    roles: channelContext.channel.roles
+  }),
+  runRoot,
+  channelConfig: channelContext.channel,
+  auditRunRoot: runRoot
+});
+const outputPath = writeTelegramBotOutput({
+  channelContext,
+  channelName,
+  responses,
+  outputOverride,
+  mode: 'dry-run'
+});
+
+console.log(`Dry-run output: ${outputPath}`);

package/scripts/telegram-check.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertEnabledChannel, loadReportChannel } from './lib/run-utils.mjs';
+import { createTelegramMessage, sendTelegramRequest, telegramEnv } from './lib/telegram-utils.mjs';
+import { createCli, fail, failAll, resolveDefault, showHelp, wantsHelp } from './lib/cli-utils.mjs';
+
+const { hasFlag, takeOption } = createCli(process.argv.slice(2));
+
+if (wantsHelp(process.argv)) {
+  showHelp({
+    command: 'telegram-test',
+    description: 'Test Telegram bot connectivity',
+    usage: [
+      'agent-os telegram-test --dry-run [options]',
+      'agent-os telegram-test --send [options]'
+    ],
+    required: [
+      { flag: '--send | --dry-run', desc: 'Send a test message or write payload to file' }
+    ],
+    options: [
+      { flag: '--channel-config <file>', desc: 'Channel config file', default: '.agent-os/project/report-channels.json' },
+      { flag: '--channel <name>', desc: 'Channel name', default: 'telegram' },
+      { flag: '--output <file>', desc: 'Override output path' }
+    ],
+    examples: [
+      'agent-os telegram-test --dry-run',
+      'agent-os telegram-test --send'
+    ]
+  });
+}
+
+const channelConfig = takeOption('--channel-config') ?? resolveDefault(null, '.agent-os/project/report-channels.json');
+const channelName = takeOption('--channel') ?? 'telegram';
+const outputOverride = takeOption('--output');
+const dryRun = hasFlag('--dry-run');
+const send = hasFlag('--send');
+
+const errors = [];
+if ((dryRun && send) || (!dryRun && !send)) errors.push('Use either --dry-run or --send (exactly one required).');
+if (!channelConfig) errors.push('Missing --channel-config <file> (no default found at .agent-os/project/report-channels.json).');
+failAll(errors, 'agent-os telegram-test --dry-run', 'telegram-test');
+
+let channelContext;
+try {
+  channelContext = loadReportChannel(channelConfig, channelName);
+  assertEnabledChannel(channelContext);
+} catch (err) {
+  fail(err.message);
+}
+
+const channel = channelContext.channel;
+if (channel.type !== 'telegram') {
+  fail(`Report channel is not a telegram channel: ${channelName}`);
+}
+
+const { botTokenEnv, chatIdEnv, botToken, chatId } = telegramEnv(channel);
+const message = createTelegramMessage({ test: true, channelName });
+
+if (send) {
+  if (!botToken) {
+    fail(`Missing required environment variable: ${botTokenEnv}`);
+  }
+  if (!chatId) {
+    fail(`Missing required environment variable: ${chatIdEnv}`);
+  }
+
+  try {
+    await sendTelegramRequest({ channel, channelContext, message, botToken, chatId });
+  } catch (err) {
+    fail(err.message);
+  }
+
+  console.log(`Channel: ${channelName}`);
+  console.log(`Sent telegram test: ${channelName}`);
+  process.exit(0);
+}
+
+const payload = {
+  channel: channelName,
+  mode: 'dry-run',
+  transport: 'telegram',
+  botTokenEnv,
+  chatIdEnv,
+  chatId,
+  message
+};
+
+const outputPath = path.resolve(channelContext.outputBaseDir, outputOverride ?? channel.testOutput ?? channel.output ?? 'reports/telegram-test.json');
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}\n`);
+console.log(`Channel: ${channelName}`);
+console.log(`Telegram test payload: ${outputPath}`);