create-amoxi-app 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+Amoxi
+Copyright 2026 Ahmad Karawash
+
+This product includes software developed by Ahmad Karawash
+(https://github.com/karawash-projects/amoxi).

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# create-amoxi-app
 
-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.
+Creates a new [Amoxi](https://www.npmjs.com/package/amoxi) app.
+
+```bash
+npx create-amoxi-app@latest my-app
+# or
+npm create amoxi-app@latest my-app
+```
+
+It asks which template to use when run in a terminal. Options: `--template web|agent|api` (pages, islands and a JSON API; the same plus an AI agent with a streaming chat; or an API only), `--no-install`, `--no-git`, `--yes`.
+
+The generated `Dockerfile` installs with whichever lockfile the project has (npm, pnpm, yarn or bun), so run your package manager's install once before `docker build`.
+
+Documentation: [karawash-projects.github.io/amoxi/docs](https://karawash-projects.github.io/amoxi/docs/).

package/index.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// Copyright 2026 Ahmad Karawash
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict';
+/**
+ * create-amoxi-app: scaffolds a ready-to-run Amoxi project.
+ *
+ *   npx create-amoxi-app@latest my-app
+ *   npx create-amoxi-app@latest my-api --template api
+ *
+ * No dependencies; works on Windows, macOS and Linux.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const VERSION = require('./package.json').version;
+const isWin = process.platform === 'win32';
+const tty = process.stdout.isTTY;
+const paint = (code) => (s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const bold = paint(1);
+const dim = paint(2);
+const green = paint(32);
+const red = paint(31);
+const cyan = paint(36);
+
+const TEMPLATES = {
+  web: 'Pages, islands and a JSON API (full-stack)',
+  agent: 'The web template plus an AI agent with tools, streaming chat and generative UI',
+  api: 'JSON API only (backend service)',
+};
+/** Templates built on top of another one: copied in order, later files win. */
+const LAYERS = { web: ['web'], agent: ['web', 'agent'], api: ['api'] };
+
+const HELP = `
+${bold('create-amoxi-app')} v${VERSION}
+
+Usage:
+  create-amoxi-app <project-name> [options]
+
+Options:
+  --template <web|agent|api>
+                         web: pages, islands and a JSON API (default)
+                         agent: web plus an AI agent with a streaming chat
+                         api: a JSON API only
+  --framework <spec>     Where amoxi comes from: a version range, a path to the
+                         framework package or a .tgz (default: the local monorepo copy if
+                         found, otherwise ^${VERSION} from npm)
+  --no-install           Don't install dependencies
+  --no-git               Don't initialise a git repository
+  -y, --yes              Accept defaults without asking
+  -h, --help             Show this help
+`;
+
+/** The project folder while it is being created: removed again if creating it fails partway. */
+let unfinished;
+
+function removeUnfinished() {
+  if (!unfinished) return;
+  const { target, existed } = unfinished;
+  unfinished = undefined;
+  try {
+    if (existed) for (const entry of fs.readdirSync(target)) fs.rmSync(path.join(target, entry), { recursive: true, force: true });
+    else fs.rmSync(target, { recursive: true, force: true });
+  } catch {
+    // Best effort: the message below still names the folder.
+  }
+}
+
+function fail(message) {
+  removeUnfinished();
+  process.stderr.write(`\n${red('error')} ${message}\n\n`);
+  process.exit(1);
+}
+
+// Ctrl+C while the files are being written: don't leave a half-made project behind.
+process.once('SIGINT', () => {
+  removeUnfinished();
+  process.exit(130);
+});
+
+/** Options that take a value (--template web or --template=web). */
+const VALUE_OPTIONS = new Set(['template', 'framework']);
+
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = { install: true, git: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') flags.help = true;
+    else if (a === '-y' || a === '--yes') flags.yes = true;
+    else if (a === '--no-install') flags.install = false;
+    else if (a === '--no-git') flags.git = false;
+    else if (a.startsWith('-') && a !== '-') {
+      const eq = a.indexOf('=');
+      const option = eq === -1 ? a : a.slice(0, eq);
+      const name = option.replace(/^--/, '');
+      // An unknown option is an error, not a reason to take the next argument (the project name) as its value.
+      if (!option.startsWith('--') || !VALUE_OPTIONS.has(name)) fail(`Unknown option ${option}. Run create-amoxi-app --help to see the options.`);
+      const value = eq === -1 ? argv[++i] : a.slice(eq + 1);
+      if (value === undefined || value === '' || (eq === -1 && value.startsWith('-'))) fail(`Missing value for --${name}`);
+      flags[name] = value;
+    } else positionals.push(a);
+  }
+  if (positionals.length > 1) fail(`Expected one project name, got ${positionals.length}: ${positionals.join(' ')}`);
+  return { positionals, flags };
+}
+
+/**
+ * How to start a package manager without a shell. On Windows npm, npx, pnpm and yarn are .cmd
+ * files, which only a shell can run, and handing argument lists to a shell is unsafe (Node warns
+ * about it, DEP0190). So they are started as Node scripts instead: the one the running package
+ * manager names in npm_execpath, or npm's own script next to node.exe. Elsewhere they run as usual.
+ */
+function packageManagerCommand(cmd, args) {
+  if (!isWin || !['npm', 'npx', 'pnpm', 'yarn'].includes(cmd)) return { file: cmd, args };
+  const execPath = process.env.npm_execpath;
+  if (execPath && fs.existsSync(execPath) && /\.(c?js|mjs)$/.test(execPath)) {
+    const base = path.basename(execPath).toLowerCase();
+    if (cmd === 'npm' && base.startsWith('npm-cli')) return { file: process.execPath, args: [execPath, ...args] };
+    const npxCli = path.join(path.dirname(execPath), 'npx-cli.js');
+    if (cmd === 'npx' && base.startsWith('npm-cli') && fs.existsSync(npxCli)) return { file: process.execPath, args: [npxCli, ...args] };
+    if (cmd !== 'npm' && cmd !== 'npx' && base.startsWith(cmd)) return { file: process.execPath, args: [execPath, ...args] };
+  }
+  const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', `${cmd === 'npx' ? 'npx' : 'npm'}-cli.js`);
+  if ((cmd === 'npm' || cmd === 'npx') && fs.existsSync(npmCli)) return { file: process.execPath, args: [npmCli, ...args] };
+  // Last resort: cmd.exe with every argument quoted; refuse characters cmd.exe would still interpret.
+  for (const a of args) {
+    if (/[%!"\r\n]/.test(a)) throw new Error(`Refusing to pass ${JSON.stringify(a)} to ${cmd} through cmd.exe`);
+  }
+  const line = [cmd, ...args].map((a) => (/^[\w./:=@\\-]+$/.test(a) ? a : `"${a}"`)).join(' ');
+  return { file: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', `"${line}"`], windowsVerbatimArguments: true };
+}
+
+/** Runs a command without a shell (see packageManagerCommand) and waits for it. */
+function run(cmd, args, options = {}) {
+  const command = packageManagerCommand(cmd, args);
+  return spawnSync(command.file, command.args, { encoding: 'utf8', windowsHide: true, windowsVerbatimArguments: command.windowsVerbatimArguments, ...options });
+}
+
+async function ask(question, fallback) {
+  if (!process.stdin.isTTY) return fallback;
+  const readline = require('node:readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = (await rl.question(`${question} ${dim(`(${fallback})`)} `)).trim();
+  rl.close();
+  return answer || fallback;
+}
+
+function validateName(name) {
+  if (name.length > 214) return 'must be at most 214 characters';
+  if (!/^[a-z0-9][a-z0-9._~-]*$/.test(name)) return 'may only contain lowercase letters, digits, "-", "_", "." and "~", and must start with a letter or digit';
+  if (['node_modules', 'favicon.ico'].includes(name)) return 'is a reserved name';
+  return undefined;
+}
+
+const DOTFILES = { _gitignore: '.gitignore', _dockerignore: '.dockerignore', '_env.example': '.env.example' };
+
+function copyTemplate(src, dest, vars) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, DOTFILES[entry.name] ?? entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(to, { recursive: true });
+      copyTemplate(from, to, vars);
+    } else {
+      let text = fs.readFileSync(from, 'utf8');
+      for (const [key, value] of Object.entries(vars)) text = text.split(`{{${key}}}`).join(value);
+      fs.writeFileSync(to, text);
+    }
+  }
+}
+
+/** Decides how the new app depends on amoxi. */
+function resolveFramework(spec, target) {
+  // Running from a clone of the Amoxi repository (packages/create-amoxi-app next to
+  // packages/framework): use that framework build, so unreleased changes can be tried.
+  // Installed from npm, there is no such sibling and the published framework is used.
+  if (!spec) {
+    const localMonorepo = path.resolve(__dirname, '..', 'framework');
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(localMonorepo, 'package.json'), 'utf8'));
+      if (pkg.name === 'amoxi' && fs.existsSync(path.join(localMonorepo, 'src', 'runtime'))) spec = localMonorepo;
+    } catch {
+      /* not a repository checkout */
+    }
+  }
+  if (!spec) return { dependency: `^${VERSION}`, note: `from npm (^${VERSION})` };
+
+  const abs = path.resolve(spec);
+  const vendor = path.join(target, 'vendor');
+  if (fs.existsSync(abs) && fs.statSync(abs).isFile() && abs.endsWith('.tgz')) {
+    fs.mkdirSync(vendor, { recursive: true });
+    fs.copyFileSync(abs, path.join(vendor, path.basename(abs)));
+    return { dependency: `file:vendor/${path.basename(abs)}`, note: `vendored from ${abs}` };
+  }
+  if (fs.existsSync(path.join(abs, 'package.json'))) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(abs, 'package.json'), 'utf8'));
+    if (pkg.name !== 'amoxi') fail(`${abs} is not the amoxi package`);
+    if (!fs.existsSync(path.join(abs, 'dist', 'runtime', 'index.js'))) {
+      fail(`The framework at ${abs} hasn't been built yet. Run "npm run build" in the Amoxi repository first.`);
+    }
+    // Pack it into the new project so the app is self-contained and portable (no symlinks).
+    fs.mkdirSync(vendor, { recursive: true });
+    const res = run('npm', ['pack', '--json', '--pack-destination', vendor], { cwd: abs });
+    if (res.status !== 0) fail(`Couldn't pack the framework:\n${res.stderr || res.stdout}`);
+    const filename = JSON.parse(res.stdout.slice(res.stdout.indexOf('[')))[0].filename;
+    return { dependency: `file:vendor/${filename}`, note: `packed from ${abs}` };
+  }
+  return { dependency: spec, note: `from npm (${spec})` };
+}
+
+function detectPackageManager() {
+  const agent = process.env.npm_config_user_agent ?? '';
+  for (const pm of ['pnpm', 'yarn', 'bun']) if (agent.startsWith(pm)) return pm;
+  return 'npm';
+}
+
+async function main() {
+  const { positionals, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < 22) fail(`Amoxi needs Node.js 22 or newer; you have ${process.version}.`);
+
+  process.stdout.write(`\n${bold('Create an Amoxi app')}\n\n`);
+  const nameArg = positionals[0] ?? (flags.yes ? 'my-amoxi-app' : await ask('Project name?', 'my-amoxi-app'));
+  const target = path.resolve(nameArg);
+  const name = path.basename(target);
+  const nameProblem = validateName(name);
+  if (nameProblem) fail(`The project name "${name}" ${nameProblem}.`);
+  if (fs.existsSync(target) && fs.readdirSync(target).length > 0) {
+    fail(`The folder ${target} already exists and isn't empty. Choose another name or remove it.`);
+  }
+
+  let template = flags.template;
+  if (!template) {
+    // Asked whenever someone is at the terminal (also when the project name was given); `web` with --yes or in scripts.
+    template = flags.yes ? 'web' : await ask(`Template? web = ${TEMPLATES.web}; agent = ${TEMPLATES.agent}; api = ${TEMPLATES.api}`, 'web');
+  }
+  if (!TEMPLATES[template]) fail(`Unknown template "${template}". Choose one of: ${Object.keys(TEMPLATES).join(', ')}.`);
+
+  const title = name.replace(/[-_.~]+/g, ' ').replace(/^\w/, (c) => c.toUpperCase());
+  unfinished = { target, existed: fs.existsSync(target) };
+  fs.mkdirSync(target, { recursive: true });
+  const vars = { APP_NAME: name, APP_TITLE: title };
+  copyTemplate(path.join(__dirname, 'templates', 'shared'), target, vars);
+  for (const layer of LAYERS[template]) copyTemplate(path.join(__dirname, 'templates', layer), target, vars);
+  if (template === 'api') {
+    // Git doesn't keep empty folders, and the Dockerfile copies public/: keep it in the repository.
+    fs.mkdirSync(path.join(target, 'public'), { recursive: true });
+    fs.writeFileSync(path.join(target, 'public', '.gitkeep'), '');
+  }
+
+  const framework = resolveFramework(flags.framework, target);
+  const pkg = {
+    name,
+    version: '0.1.0',
+    private: true,
+    scripts: {
+      dev: 'amoxi dev',
+      build: 'amoxi build && tsc -p tsconfig.json',
+      start: 'amoxi start dist/src/main.js',
+      test: 'npm run build && node --test "dist/test/*.test.js"',
+    },
+    dependencies: { 'amoxi': framework.dependency },
+    devDependencies: { '@types/node': '^22.0.0', typescript: '~5.9.3' },
+    engines: { node: '>=22' },
+  };
+  fs.writeFileSync(path.join(target, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+  // Every file is written: from here on the project stays, even if installing fails.
+  unfinished = undefined;
+
+  process.stdout.write(`${green('ok')} Created ${bold(name)} (${template} template) in ${target}\n`);
+  process.stdout.write(`${green('ok')} amoxi ${framework.note}\n`);
+
+  const pm = detectPackageManager();
+  let installFailed = false;
+  if (flags.install) {
+    process.stdout.write(`\nInstalling dependencies with ${pm}...\n\n`);
+    const res = run(pm, ['install'], { cwd: target, stdio: 'inherit' });
+    if (res.status !== 0) {
+      installFailed = true;
+      process.stdout.write(`\n${red('error')} Installing dependencies failed. Fix the problem above, then run "${pm} install" in ${name}.\n`);
+    } else {
+      process.stdout.write(`\n${green('ok')} Dependencies installed\n`);
+    }
+  }
+
+  if (flags.git && run('git', ['--version']).status === 0 && !fs.existsSync(path.join(target, '.git'))) {
+    const inRepo = run('git', ['rev-parse', '--is-inside-work-tree'], { cwd: target }).stdout?.trim() === 'true';
+    if (!inRepo && run('git', ['init', '-q'], { cwd: target }).status === 0) {
+      run('git', ['add', '-A'], { cwd: target });
+      const commit = run('git', ['commit', '-q', '-m', 'Initial commit from create-amoxi-app'], { cwd: target });
+      process.stdout.write(`${green('ok')} Initialised a git repository${commit.status === 0 ? ' with an initial commit' : ''}\n`);
+    }
+  }
+
+  const runCmd = pm === 'npm' ? 'npm run' : pm;
+  const rel = path.relative(process.cwd(), target) || '.';
+  process.stdout.write(`
+${bold('Next steps')}
+
+  ${cyan(`cd ${rel.includes(' ') ? `"${rel}"` : rel}`)}${flags.install && !installFailed ? '' : `\n  ${cyan(`${pm} install`)}`}
+  ${cyan(`${runCmd} dev`)}      then open http://localhost:8080
+
+  ${runCmd} build    production build
+  ${pm === 'npm' ? 'npm start' : `${pm} start`}        run it on every CPU core
+  ${pm === 'npm' ? 'npm test' : `${pm} test`}         build and run the tests
+
+`);
+  // The project was created, but it isn't ready: scripts and CI must see the failure.
+  if (installFailed) process.exitCode = 1;
+}
+
+main().catch((err) => fail(err instanceof Error ? err.stack : String(err)));

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "create-amoxi-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Create an Amoxi app: npx create-amoxi-app@latest my-app",
+  "keywords": [
+    "amoxi",
+    "create",
+    "scaffold",
+    "template"
+  ],
+  "homepage": "https://karawash-projects.github.io/amoxi/",
+  "bugs": {
+    "url": "https://github.com/karawash-projects/amoxi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karawash-projects/amoxi.git",
+    "directory": "packages/create-amoxi-app"
+  },
+  "license": "Apache-2.0",
+  "author": "Ahmad Karawash",
+  "bin": {
+    "create-amoxi-app": "index.js"
+  },
+  "files": [
+    "index.js",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "node ../../scripts/check-package.mjs",
+    "test": "node --test \"test/*.test.cjs\""
+  }
+}

package/templates/LICENSE

@@ -0,0 +1,22 @@
+Starter templates for create-amoxi-app
+
+The files in this folder are copied into the projects that create-amoxi-app
+generates. They are licensed under the Zero-Clause BSD license (SPDX: 0BSD)
+below, so a generated project is yours to use, change and license however you
+like, with no attribution required. The create-amoxi-app tool itself is
+licensed under the Apache License 2.0 (see ../LICENSE).
+
+-------------------------------------------------------------------------------
+
+Copyright (C) 2026 by Ahmad Karawash
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/templates/agent/README.md

@@ -0,0 +1,34 @@
+# {{APP_TITLE}}
+
+Created with `create-amoxi-app`.
+
+## Commands
+
+| | |
+|---|---|
+| `npm run dev` | Development server on http://localhost:8080; rebuilds and refreshes the browser on save |
+| `npm run build` | Production build: `amoxi build` (wiring, validators, browser bundles) then `tsc` |
+| `npm start` | Run the production build on every CPU core (`NODE_ENV=production`) |
+| `npm test` | Build, then run the tests in `test/` |
+
+## Configuration
+
+No environment variables are required. Settings come from `application.json`, then `application-<profile>.json`, then `.env` files, then environment variables. The profile is `production` under `npm start` and `development` under `npm run dev`.
+
+## Deploy
+
+```bash
+docker build -t {{APP_NAME}} .
+docker run -p 8080:8080 {{APP_NAME}}
+```
+
+Health checks: `GET /amoxi/health/live` and `GET /amoxi/health/ready`.
+
+## The AI assistant
+
+`src/agent/` holds an agent (`@Agent`) and its tools (`@Tool`); `src/islands/Assistant.tsx` is the chat and `src/islands/NoteList.tsx` a component the agent can show (`@generative`). Open http://localhost:8080/assistant and try the suggested prompts.
+
+- **No API key needed:** without one, Amoxi uses an offline demo model that picks tools by keyword. To use a real model, create `.env` (git-ignored, so the key is never committed) with `ANTHROPIC_API_KEY=...` or `OPENAI_API_KEY=...` (`OPENAI_BASE_URL` for Ollama, Azure OpenAI or another compatible server).
+- **API:** `POST /agents/assistant/runs` with `{ "input": "Show my notes" }` (add `Accept: text/event-stream` to stream), then `GET /agents/assistant/runs/<id>`.
+- **Storage:** conversations and runs are kept in `data/ai/`. Use PostgreSQL in production (see the Amoxi README, "AI agents").
+- **Tests:** `test/agent.test.ts` shows the offline model and a scripted model (`ScriptedChatModel`) driving the agent deterministically.

package/templates/agent/src/agent/assistant.ts

@@ -0,0 +1,18 @@
+import { Agent, type AgentRunContext } from 'amoxi/ai';
+import { NoteTools } from './note-tools';
+
+/** Answers questions about your notes and writes new ones. */
+@Agent({
+  tools: [NoteTools],
+  ui: ['NoteList'],
+  examples: ['Show my notes', 'Add a note "Buy coffee beans"'],
+})
+export class Assistant {
+  instructions(ctx: AgentRunContext): string {
+    return [
+      'You are the assistant of a small notes app. Be brief and friendly.',
+      'Use the tools to read and save notes; never invent notes.',
+      `Today is ${ctx.now.toDateString()}.`,
+    ].join('\n');
+  }
+}