aios-lite 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-01
+### Added
+- Initial CLI commands: init, install, update, info, doctor
+- Multi-IDE template gateways (Claude, Codex, Gemini, OpenCode)
+- Framework detector and installer/updater core
+- i18n message system with English default
+- Automated tests for detector, installer, doctor, i18n
+- `i18n:add <locale>` command to scaffold new locale dictionaries
+- GitHub Actions CI and tag-based npm release workflows
+
+### Changed
+- Project-facing content standardized to English
+- CLI i18n upgraded with dynamic locale loading and fallback behavior

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,12 @@
+# Code of Conduct
+
+Be respectful, inclusive, and constructive.
+
+## Expected behavior
+- Use welcoming and professional language.
+- Focus on technical feedback and collaborative problem solving.
+- Assume good intent.
+
+## Unacceptable behavior
+- Harassment, insults, discrimination, or intimidation.
+- Personal attacks or hostile communication.

package/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+## Development
+1. Fork the repository.
+2. Create a branch from main.
+3. Run tests: `npm test`.
+4. Run lint checks: `npm run lint`.
+5. Open a pull request with a clear description.
+
+## Commit style
+Use Conventional Commits, for example:
+- `feat(cli): add doctor command output hints`
+- `fix(detector): avoid false positives for Node projects`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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/README.md

@@ -0,0 +1,47 @@
+# AIOS Lite
+
+Lightweight AI agent framework for software projects.
+
+## Install
+
+```bash
+npx aios-lite init my-project
+# or
+npx aios-lite install
+```
+
+## Commands
+- `aios-lite init <project-name>`
+- `aios-lite install [path]`
+- `aios-lite update [path]`
+- `aios-lite info [path]`
+- `aios-lite doctor [path]`
+- `aios-lite i18n:add <locale>`
+
+## i18n
+CLI localization is supported with:
+- `--locale=<code>`
+- `AIOS_LITE_LOCALE=<code>`
+
+Default locale is `en`.
+
+Generate a new locale scaffold:
+
+```bash
+aios-lite i18n:add fr
+```
+
+## Multi-IDE support
+- Claude Code (`CLAUDE.md`)
+- Codex CLI (`AGENTS.md`)
+- Gemini CLI (`.gemini/GEMINI.md`)
+- OpenCode (`OPENCODE.md`)
+
+## Docs
+- i18n guide: `docs/en/i18n.md`
+- release guide: `docs/en/release.md`
+- release flow: `docs/en/release-flow.md`
+- release notes template: `docs/en/release-notes-template.md`
+
+## License
+MIT

package/bin/aios-lite.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/cli.js');

package/docs/en/i18n.md

@@ -0,0 +1,23 @@
+# i18n Guide
+
+AIOS Lite CLI supports localization through message dictionaries.
+
+## How it works
+- Dictionaries are stored in `src/i18n/messages/`.
+- `src/i18n/index.js` resolves locale and fallback behavior.
+- Commands use translation keys instead of hardcoded strings.
+
+## Runtime selection
+- CLI option: `--locale=en`
+- Env var: `AIOS_LITE_LOCALE=en`
+- Default: `en`
+
+## Create a locale scaffold
+```bash
+aios-lite i18n:add fr
+```
+
+## Add a new locale
+1. Run `aios-lite i18n:add <locale>`.
+2. Replace English strings in `src/i18n/messages/<locale>.js`.
+3. Add tests for locale resolution and fallback behavior.

package/docs/en/release-flow.md

@@ -0,0 +1,23 @@
+# Release Tag Flow
+
+## Preconditions
+- Git repository initialized and connected to GitHub.
+- `NPM_TOKEN` configured in repository secrets.
+- `main` branch green in CI.
+
+## Steps
+1. Update `CHANGELOG.md` and `package.json` version.
+2. Run local validation:
+   - `npm run ci`
+3. Commit release changes.
+4. Create tag:
+   - `git tag vX.Y.Z`
+5. Push branch and tag:
+   - `git push origin main --tags`
+6. Watch `Release` workflow in GitHub Actions.
+7. Publish GitHub release using `.github/release-notes-template.md`.
+
+## Verify publication
+- `npm view aios-lite version`
+- `npx aios-lite@latest info`
+

package/docs/en/release-notes-template.md

@@ -0,0 +1,41 @@
+# Release Notes Template
+
+## AIOS Lite vX.Y.Z
+
+### Highlights
+- [short summary 1]
+- [short summary 2]
+- [short summary 3]
+
+### Added
+- [feature]
+- [feature]
+
+### Changed
+- [change]
+- [change]
+
+### Fixed
+- [bug fix]
+- [bug fix]
+
+### CLI
+- Commands impacted: `[list]`
+- Breaking changes: `yes/no` (if yes, describe migration)
+
+### i18n
+- New locale scaffolds or translation keys:
+  - [item]
+
+### Upgrade notes
+1. Update package:
+   - `npx aios-lite@latest update`
+2. Run health check:
+   - `aios-lite doctor`
+3. Verify local customizations in `.aios-lite/backups/` if applicable.
+
+### Checks
+- [ ] Lint passed
+- [ ] Tests passed
+- [ ] Smoke test passed
+

package/docs/en/release.md

@@ -0,0 +1,32 @@
+# Release Guide
+
+## CI
+- Workflow: `.github/workflows/ci.yml`
+- Triggers: push to `main`, pull requests
+- Steps: install, lint, test, `npm pack --dry-run`
+
+## npm publish
+- Workflow: `.github/workflows/release.yml`
+- Triggers: `v*` git tags or manual dispatch
+- Required secret: `NPM_TOKEN`
+
+## Name availability snapshot (2026-03-01)
+The following names returned `404 Not Found` from npm registry lookup and were therefore available at the time of check:
+- `aios-lite`
+- `aios-lite-cli`
+- `create-aios-lite`
+- `@aios-lite/create`
+- `@synkra-ai/aios-lite`
+- `@synkra-ai/create-aios-lite`
+
+## Recommended release flow
+1. Update `CHANGELOG.md`.
+2. Bump version in `package.json`.
+3. Commit and push to `main`.
+4. Create and push a tag like `v0.1.1`.
+5. Verify publish logs in GitHub Actions.
+
+## Templates
+- Release notes template: `.github/release-notes-template.md`
+- Extended release notes guide: `docs/en/release-notes-template.md`
+- Tag flow checklist: `docs/en/release-flow.md`

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "aios-lite",
+  "version": "0.1.0",
+  "description": "Lightweight AI agent framework for software projects.",
+  "keywords": [
+    "ai",
+    "agents",
+    "claude",
+    "codex",
+    "gemini",
+    "opencode",
+    "cli",
+    "framework"
+  ],
+  "license": "MIT",
+  "main": "src/cli.js",
+  "bin": {
+    "aios-lite": "bin/aios-lite.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/",
+    "docs/",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "node --check src/*.js src/commands/*.js src/i18n/*.js src/i18n/messages/*.js bin/*.js",
+    "ci": "npm run lint && npm test"
+  }
+}

package/src/cli.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const { parseArgv } = require('./parser');
+const { createTranslator, normalizeLocale } = require('./i18n');
+const { runInit } = require('./commands/init');
+const { runInstall } = require('./commands/install');
+const { runUpdate } = require('./commands/update');
+const { runInfo } = require('./commands/info');
+const { runDoctorCommand } = require('./commands/doctor');
+const { runI18nAdd } = require('./commands/i18n-add');
+
+function printHelp(t) {
+  console.log(`${t('cli.title')}\n`);
+  console.log(t('cli.usage'));
+  console.log(`  ${t('cli.help_init')}`);
+  console.log(`  ${t('cli.help_install')}`);
+  console.log(`  ${t('cli.help_update')}`);
+  console.log(`  ${t('cli.help_info')}`);
+  console.log(`  ${t('cli.help_doctor')}`);
+  console.log(`  ${t('cli.help_i18n_add')}`);
+}
+
+async function main() {
+  const { command, args, options } = parseArgv(process.argv);
+  const locale = normalizeLocale(options.locale || process.env.AIOS_LITE_LOCALE || 'en');
+  const { t } = createTranslator(locale);
+  const logger = console;
+
+  if (command === 'help' || options.help || command === '--help' || command === '-h') {
+    printHelp(t);
+    return;
+  }
+
+  if (command === '--version' || command === '-v' || command === 'version' || options.version) {
+    await runInfo({ args: ['.'], options: {}, logger, t });
+    return;
+  }
+
+  try {
+    if (command === 'init') {
+      await runInit({ args, options, logger, t });
+      return;
+    }
+    if (command === 'install') {
+      await runInstall({ args, options, logger, t });
+      return;
+    }
+    if (command === 'update') {
+      await runUpdate({ args, options, logger, t });
+      return;
+    }
+    if (command === 'info') {
+      await runInfo({ args, options, logger, t });
+      return;
+    }
+    if (command === 'doctor') {
+      await runDoctorCommand({ args, options, logger, t });
+      return;
+    }
+    if (command === 'i18n:add' || command === 'i18n-add') {
+      await runI18nAdd({ args, options, logger, t });
+      return;
+    }
+
+    logger.error(`${t('cli.unknown_command', { command })}\n`);
+    printHelp(t);
+    process.exitCode = 1;
+  } catch (error) {
+    logger.error(t('cli.error_prefix', { message: error.message }));
+    process.exitCode = 1;
+  }
+}
+
+main();

package/src/commands/doctor.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const path = require('node:path');
+const { runDoctor } = require('../doctor');
+
+async function runDoctorCommand({ args, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const report = await runDoctor(targetDir);
+
+  for (const check of report.checks) {
+    const icon = check.ok ? t('doctor.ok') : t('doctor.fail');
+    logger.log(`[${icon}] ${t(check.key, check.params)}`);
+    if (!check.ok && check.hintKey) {
+      logger.log(`  ${t('doctor.hint_prefix', { hint: t(check.hintKey) })}`);
+    }
+  }
+
+  if (!report.ok) {
+    logger.log(`\n${t('doctor.diagnosis_fail', { count: report.failedCount })}`);
+  } else {
+    logger.log(`\n${t('doctor.diagnosis_ok')}`);
+  }
+
+  return report;
+}
+
+module.exports = {
+  runDoctorCommand
+};

package/src/commands/i18n-add.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const { createLocaleScaffold } = require('../i18n/scaffold');
+
+async function runI18nAdd({ args, options, logger, t }) {
+  const requestedLocale = args[0];
+  if (!requestedLocale) {
+    throw new Error(t('i18n_add.usage_error'));
+  }
+
+  const force = Boolean(options.force);
+  const dryRun = Boolean(options['dry-run']);
+
+  let result;
+  try {
+    result = await createLocaleScaffold(requestedLocale, { force, dryRun });
+  } catch (error) {
+    if (error.code === 'INVALID_LOCALE') {
+      throw new Error(t('i18n_add.invalid_locale', { locale: requestedLocale }));
+    }
+    if (error.code === 'BASE_LOCALE') {
+      throw new Error(t('i18n_add.base_locale'));
+    }
+    if (error.code === 'LOCALE_EXISTS') {
+      throw new Error(t('i18n_add.locale_exists', { path: error.path }));
+    }
+    throw error;
+  }
+
+  if (result.dryRun) {
+    logger.log(
+      result.overwritten
+        ? t('i18n_add.dry_run_overwritten', { locale: result.locale })
+        : t('i18n_add.dry_run_created', { locale: result.locale })
+    );
+  } else {
+    logger.log(
+      result.overwritten
+        ? t('i18n_add.overwritten', { locale: result.locale })
+        : t('i18n_add.created', { locale: result.locale })
+    );
+  }
+  logger.log(t('i18n_add.file_path', { path: result.filePath }));
+  logger.log(t('i18n_add.next_steps'));
+  logger.log(t('i18n_add.step_translate'));
+  logger.log(t('i18n_add.step_try', { locale: result.locale }));
+
+  return result;
+}
+
+module.exports = {
+  runI18nAdd
+};

package/src/commands/info.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { detectFramework } = require('../detector');
+const { detectExistingInstall } = require('../installer');
+
+async function runInfo({ args, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const pkgPath = path.join(__dirname, '../../package.json');
+  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+
+  const installed = await detectExistingInstall(targetDir);
+  const detection = await detectFramework(targetDir);
+
+  logger.log(t('info.cli_version', { version: pkg.version }));
+  logger.log(t('info.directory', { targetDir }));
+  logger.log(t('info.installed_here', { value: installed ? t('info.yes') : t('info.no') }));
+  logger.log(t('info.framework_detected', { framework: detection.framework || t('info.none') }));
+  if (detection.evidence) {
+    logger.log(t('info.evidence', { evidence: detection.evidence }));
+  }
+
+  return {
+    version: pkg.version,
+    installed,
+    detection
+  };
+}
+
+module.exports = {
+  runInfo
+};

package/src/commands/init.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { installTemplate } = require('../installer');
+
+async function directoryIsEmpty(dirPath) {
+  try {
+    const entries = await fs.readdir(dirPath);
+    return entries.length === 0;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return true;
+    throw error;
+  }
+}
+
+async function runInit({ args, options, logger, t }) {
+  const projectName = args[0];
+  if (!projectName) {
+    throw new Error(t('init.usage_error'));
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+  const force = Boolean(options.force);
+  const dryRun = Boolean(options['dry-run']);
+
+  await fs.mkdir(targetDir, { recursive: true });
+
+  if (!(await directoryIsEmpty(targetDir)) && !force) {
+    throw new Error(t('init.non_empty_dir', { targetDir }));
+  }
+
+  const result = await installTemplate(targetDir, {
+    overwrite: true,
+    dryRun,
+    mode: 'init'
+  });
+
+  logger.log(t('init.created_at', { targetDir }));
+  logger.log(t('init.files_copied', { count: result.copied.length }));
+  if (result.skipped.length > 0) {
+    logger.log(t('init.files_skipped', { count: result.skipped.length }));
+  }
+  logger.log(t('init.next_steps'));
+  logger.log(t('init.step_cd', { projectName }));
+  logger.log(t('init.step_setup'));
+
+  return result;
+}
+
+module.exports = {
+  runInit,
+  directoryIsEmpty
+};

package/src/commands/install.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const path = require('node:path');
+const { detectFramework } = require('../detector');
+const { installTemplate } = require('../installer');
+
+async function runInstall({ args, options, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const force = Boolean(options.force);
+  const dryRun = Boolean(options['dry-run']);
+
+  const detection = await detectFramework(targetDir);
+  if (detection.installed) {
+    logger.log(t('install.framework_detected', {
+      framework: detection.framework,
+      evidence: detection.evidence
+    }));
+  } else {
+    logger.log(t('install.framework_not_detected'));
+  }
+
+  const result = await installTemplate(targetDir, {
+    overwrite: force,
+    dryRun,
+    mode: 'install',
+    frameworkDetection: detection.framework
+  });
+
+  logger.log(t('install.done_at', { targetDir }));
+  logger.log(t('install.files_copied', { count: result.copied.length }));
+  logger.log(t('install.files_skipped', { count: result.skipped.length }));
+
+  return result;
+}
+
+module.exports = {
+  runInstall
+};

package/src/commands/update.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const path = require('node:path');
+const { detectFramework } = require('../detector');
+const { updateInstallation } = require('../updater');
+
+async function runUpdate({ args, options, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const dryRun = Boolean(options['dry-run']);
+
+  const detection = await detectFramework(targetDir);
+  const result = await updateInstallation(targetDir, {
+    dryRun,
+    frameworkDetection: detection.framework
+  });
+
+  if (!result.ok) {
+    throw new Error(t('update.not_installed', { targetDir }));
+  }
+
+  logger.log(t('update.done_at', { targetDir }));
+  logger.log(t('update.files_updated', { count: result.copied.length }));
+  logger.log(t('update.backups_created', { count: result.backedUp.length }));
+
+  return result;
+}
+
+module.exports = {
+  runUpdate
+};

package/src/constants.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const MANAGED_FILES = [
+  'CLAUDE.md',
+  'AGENTS.md',
+  'OPENCODE.md',
+  '.gemini/GEMINI.md',
+  '.gemini/commands/aios-setup.toml',
+  '.gemini/commands/aios-analyst.toml',
+  '.gemini/commands/aios-architect.toml',
+  '.gemini/commands/aios-pm.toml',
+  '.gemini/commands/aios-dev.toml',
+  '.gemini/commands/aios-qa.toml',
+  '.gemini/commands/aios-orchestrator.toml',
+  '.aios-lite/config.md',
+  '.aios-lite/agents/setup.md',
+  '.aios-lite/agents/analyst.md',
+  '.aios-lite/agents/architect.md',
+  '.aios-lite/agents/pm.md',
+  '.aios-lite/agents/dev.md',
+  '.aios-lite/agents/qa.md',
+  '.aios-lite/agents/orchestrator.md',
+  '.aios-lite/skills/static/laravel-conventions.md',
+  '.aios-lite/skills/static/tall-stack-patterns.md',
+  '.aios-lite/skills/static/jetstream-setup.md',
+  '.aios-lite/skills/static/rails-conventions.md',
+  '.aios-lite/skills/static/node-express-patterns.md',
+  '.aios-lite/skills/static/nextjs-patterns.md',
+  '.aios-lite/skills/static/ui-ux-modern.md',
+  '.aios-lite/skills/static/git-conventions.md',
+  '.aios-lite/skills/dynamic/laravel-docs.md',
+  '.aios-lite/skills/dynamic/flux-ui-docs.md',
+  '.aios-lite/skills/dynamic/npm-packages.md',
+  '.aios-lite/mcp/servers.md'
+];
+
+const REQUIRED_FILES = [
+  'CLAUDE.md',
+  'AGENTS.md',
+  '.aios-lite/config.md',
+  '.aios-lite/agents/setup.md',
+  '.aios-lite/agents/analyst.md',
+  '.aios-lite/agents/dev.md',
+  '.aios-lite/context/.gitkeep'
+];
+
+module.exports = {
+  MANAGED_FILES,
+  REQUIRED_FILES
+};