azoxjs 0.1.0

package/core/commands/create.js

@@ -0,0 +1,146 @@
+// `azox create <name>` — scaffolds a new Azox project.
+//
+// Generated projects import the runtime by its package name
+// ("azox/reactivity"), which is what will work once Azox is on npm.
+// Until then `npm link azox` from the framework checkout makes the
+// same specifier resolve locally, so the scaffold never has to bake
+// in a brittle relative path.
+
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+import { BANNER, VERSION } from '../meta.js';
+
+export function createCommand({ positionals, flags }) {
+  const name = positionals[0] ?? flags.name;
+
+  if (!name) {
+    console.error('Azox: missing project name.');
+    console.error('Usage: azox create <name>');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(name)) {
+    console.error(`Azox: "${name}" is not a valid project name.`);
+    console.error('Use letters, digits, dots, dashes or underscores.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const targetDir = resolve(process.cwd(), name);
+
+  if (existsSync(targetDir)) {
+    console.error(`Azox: directory "${name}" already exists.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  mkdirSync(join(targetDir, 'pages'), { recursive: true });
+  mkdirSync(join(targetDir, 'components'), { recursive: true });
+
+  const files = {
+    'package.json': projectPackageJson(name),
+    'pages/index.azox': starterPage(name),
+    'pages/about.azox': aboutPage(name),
+    'components/Counter.azox': starterComponent(),
+    '.gitignore': '.azox/\nnode_modules/\n.DS_Store\n',
+    'README.md': projectReadme(name),
+  };
+
+  for (const [path, contents] of Object.entries(files)) {
+    writeFileSync(join(targetDir, path), contents, 'utf8');
+  }
+
+  console.log(BANNER);
+  console.log('');
+  console.log(`Created ${name}/`);
+  for (const path of Object.keys(files)) console.log(`  ${path}`);
+  console.log('');
+  console.log('Next:');
+  console.log(`  cd ${name}`);
+  console.log('  npm install');
+  console.log('  npx azox dev');
+}
+
+function projectPackageJson(name) {
+  return `${JSON.stringify(
+    {
+      name,
+      version: '0.1.0',
+      private: true,
+      type: 'module',
+      scripts: {
+        dev: 'azox dev',
+        build: 'azox compile',
+      },
+      devDependencies: {
+        azoxjs: `^${VERSION}`,
+      },
+    },
+    null,
+    2
+  )}\n`;
+}
+
+function starterPage(name) {
+  return `<script>
+  import Counter from '../components/Counter.azox';
+  import { signal } from 'azox/reactivity';
+
+  const count = signal(0);
+</script>
+
+<main class="page">
+  <h1>${name}</h1>
+  <p>Built with Azox.</p>
+
+  <Counter label="Clicks" value={count()} />
+
+  <button on:click={() => count.set(count() + 1)}>
+    Add one
+  </button>
+
+  <p><a href="/about">About</a></p>
+</main>
+`;
+}
+
+// pages/about.azox is served at /about — the file layout is the
+// routing table.
+function aboutPage(name) {
+  return `<main class="page">
+  <h1>About</h1>
+  <p>${name} is built with Azox.</p>
+  <p><a href="/">Home</a></p>
+</main>
+`;
+}
+
+// Components take props and render markup. State lives in the page
+// that uses them.
+function starterComponent() {
+  return `<script>
+  const { label, value } = props();
+</script>
+
+<p class="counter">{label}: {value}</p>
+`;
+}
+
+function projectReadme(name) {
+  return `# ${name}
+
+An Azox project.
+
+## Build
+
+\`\`\`bash
+azox compile
+\`\`\`
+
+Output lands in \`.azox/build/\`.
+`;
+}
+
+const toPosix = (p) => p.split('\\').join('/');

package/core/commands/dev.js

@@ -0,0 +1,127 @@
+// `azox dev` — builds the project, serves it, and rebuilds and
+// reloads the browser whenever a source file changes.
+//
+//   azox dev
+//   azox dev --port=5000 --host=0.0.0.0 --open
+
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+import { buildAll, BuildError, PAGES_DIR, BUILD_DIR } from '../build.js';
+import { createDevServer } from '../dev/server.js';
+import { watchDirectory } from '../dev/watcher.js';
+import { injectLiveReload } from '../dev/liveReload.js';
+import { BANNER } from '../meta.js';
+
+const DEFAULT_PORT = 4321;
+const DEFAULT_HOST = 'localhost';
+const MAX_PORT_ATTEMPTS = 10;
+
+export async function devCommand({ flags }) {
+  const projectDir = process.cwd();
+  const pagesDir = resolve(projectDir, PAGES_DIR);
+
+  if (!existsSync(pagesDir)) {
+    console.error(`Azox: no ${PAGES_DIR}/ directory in ${projectDir}.`);
+    console.error('Run "azox create <name>" to start a project.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const host = typeof flags.host === 'string' ? flags.host : DEFAULT_HOST;
+  const requestedPort = Number(flags.port) || DEFAULT_PORT;
+
+  console.log(BANNER);
+  console.log('');
+
+  // Build once up front so the first request is served from output
+  // that already exists.
+  const built = rebuild(projectDir);
+  if (!built.ok) reportFailure(built.error);
+
+  const dev = createDevServer({ rootDir: resolve(projectDir, BUILD_DIR) });
+  dev.setBuildError(built.ok ? null : built.error);
+
+  let port;
+  try {
+    port = await listenOnFreePort(dev, requestedPort, host);
+  } catch (error) {
+    console.error(`Azox: could not start the dev server — ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const url = `http://${host}:${port}`;
+  console.log(`  Local:   ${url}`);
+  console.log(`  Pages:   ${built.ok ? built.results.length : 0}`);
+  console.log('');
+  console.log('  Watching for changes. Press Ctrl+C to stop.');
+  console.log('');
+
+  const stopWatching = watchDirectory(
+    pagesDir,
+    (filename) => {
+      const result = rebuild(projectDir);
+      dev.setBuildError(result.ok ? null : result.error);
+
+      if (result.ok) {
+        console.log(`  rebuilt${filename ? ` (${filename})` : ''}`);
+      } else {
+        reportFailure(result.error);
+      }
+
+      // Reload either way: on failure the browser picks up the error
+      // page the server renders in place of the build output.
+      dev.reload();
+    },
+    { filter: (filename) => filename.endsWith('.azox') }
+  );
+
+  const shutdown = async () => {
+    stopWatching();
+    await dev.close();
+    console.log('\nAzox: dev server stopped.');
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+function rebuild(projectDir) {
+  try {
+    return { ok: true, results: buildAll(projectDir, { transformHtml: injectLiveReload }) };
+  } catch (error) {
+    if (!(error instanceof BuildError)) throw error;
+    return { ok: false, error };
+  }
+}
+
+function reportFailure(error) {
+  console.error(`  build failed: ${error.message}`);
+}
+
+// A dev server that dies because the port is taken is a bad first
+// impression, so step forward until a free one is found.
+async function listenOnFreePort(dev, startPort, host) {
+  for (let offset = 0; offset < MAX_PORT_ATTEMPTS; offset++) {
+    const port = startPort + offset;
+
+    try {
+      await new Promise((done, fail) => {
+        dev.server.once('error', fail);
+        dev.listen(port, host).then(() => {
+          dev.server.removeListener('error', fail);
+          done();
+        }, fail);
+      });
+
+      if (offset > 0) console.log(`  Port ${startPort} was busy, using ${port}.`);
+      return port;
+    } catch (error) {
+      if (error.code !== 'EADDRINUSE') throw error;
+    }
+  }
+
+  throw new Error(`ports ${startPort}-${startPort + MAX_PORT_ATTEMPTS - 1} are all in use`);
+}

package/core/commands/doctor.js

@@ -0,0 +1,68 @@
+// `azox doctor` — checks that the toolchain and the current project
+// are in a working state, and reports what it finds.
+
+import { readFileSync } from 'node:fs';
+
+import { parseAzox } from '../compiler/parser.js';
+import { resolveComponents } from '../compiler/resolveComponents.js';
+import { listRoutes, PAGES_DIR } from '../build.js';
+import { BANNER, VERSION } from '../meta.js';
+
+const MIN_NODE_MAJOR = 18;
+
+export function doctorCommand() {
+  const projectDir = process.cwd();
+  const checks = [];
+
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  checks.push({
+    ok: nodeMajor >= MIN_NODE_MAJOR,
+    label: `Node ${process.versions.node}`,
+    detail: nodeMajor >= MIN_NODE_MAJOR ? null : `Azox needs Node ${MIN_NODE_MAJOR} or newer`,
+  });
+
+  checks.push({ ok: true, label: `Azox v${VERSION}` });
+
+  const routes = listRoutes(projectDir);
+
+  checks.push({
+    ok: routes.length > 0,
+    label: `${PAGES_DIR}/ (${routes.length} page${routes.length === 1 ? '' : 's'})`,
+    detail: routes.length
+      ? null
+      : `No .azox pages found — run "azox create <name>" to start one`,
+  });
+
+  // Fully resolve every page — parse it and its components — so a
+  // broken reference surfaces here rather than halfway through a
+  // build.
+  for (const route of routes) {
+    try {
+      resolveComponents(parseAzox(readFileSync(route.sourcePath, 'utf8')), route.sourcePath);
+      checks.push({ ok: true, label: `${route.url}`, note: `${PAGES_DIR}/${route.name}.azox` });
+    } catch (error) {
+      checks.push({
+        ok: false,
+        label: `${route.url}`,
+        note: `${PAGES_DIR}/${route.name}.azox`,
+        detail: error.message,
+      });
+    }
+  }
+
+  console.log(BANNER);
+  console.log('');
+  for (const check of checks) {
+    console.log(`  ${check.ok ? '✓' : '✗'} ${check.label}${check.note ? `  (${check.note})` : ''}`);
+    if (check.detail) console.log(`      ${check.detail}`);
+  }
+  console.log('');
+
+  const failures = checks.filter((check) => !check.ok).length;
+  if (failures) {
+    console.log(`${failures} problem${failures === 1 ? '' : 's'} found.`);
+    process.exitCode = 1;
+  } else {
+    console.log('Everything looks good.');
+  }
+}

package/core/commands/help.js

@@ -0,0 +1,31 @@
+// `azox help` / `azox --help` / bare `azox`
+//
+// Reads its content straight from the command registry so the help
+// output can never fall out of step with what the CLI actually does.
+
+import { BANNER } from '../meta.js';
+
+export function helpCommand({ registry }) {
+  const names = Object.keys(registry);
+  const width = Math.max(...names.map((n) => n.length));
+
+  console.log(BANNER);
+  console.log('');
+  console.log('Usage: azox <command> [options]');
+  console.log('');
+  console.log('Commands:');
+  for (const name of names) {
+    console.log(`  ${name.padEnd(width)}  ${registry[name].describe}`);
+  }
+  console.log('');
+  console.log('Options:');
+  console.log('  -v, --version  Print the Azox version');
+  console.log('  -h, --help     Show this help');
+  console.log('');
+  console.log('Examples:');
+  for (const name of names) {
+    for (const example of registry[name].examples ?? []) {
+      console.log(`  ${example}`);
+    }
+  }
+}

package/core/commands/version.js

@@ -0,0 +1,7 @@
+// `azox version` / `azox -v` / `azox --version`
+
+import { VERSION } from '../meta.js';
+
+export function versionCommand() {
+  console.log(`azox v${VERSION}`);
+}

package/core/compiler/compileToJs.js

@@ -0,0 +1,139 @@
+// Turns a parsed .azox AST into a JS module. The generated `render`
+// function builds real DOM nodes and wires each dynamic binding to
+// its own effect — no Virtual DOM tree, no diffing. A signal update
+// touches exactly the text node or attribute it owns.
+
+import { relative, dirname, resolve } from 'node:path';
+
+let uid = 0;
+const nextId = () => `_el${uid++}`;
+
+// sourcePath: absolute path of the .azox file being compiled.
+// outPath: absolute path of the client module being written.
+// runtimeSpecifier: how the emitted module should import the Azox
+//   runtime — a bare "azox/reactivity" for user projects, or a
+//   relative path when compiling inside the framework itself.
+//
+// Relative import specifiers in the user's <script> are resolved
+// against sourcePath and re-expressed relative to outPath, since
+// compiled output lives in .azox/build/, not next to the page.
+// Bare specifiers are left untouched for the resolver to handle.
+export function compileToModule(ast, { sourcePath, outPath, runtimeSpecifier }) {
+  uid = 0;
+  const statements = [];
+  const rootVar = emitNode(ast.markup, statements, 'root');
+  const script = rebaseImports(dropComponentImports(ast.script), dirname(sourcePath), outPath);
+
+  return `
+import { effect } from '${runtimeSpecifier}';
+${script}
+
+export function render(mount) {
+${statements.map((line) => '  ' + line).join('\n')}
+  mount.appendChild(${rootVar});
+  return ${rootVar};
+}
+
+// Hydrate: the SSR markup is already on the page, so clear it and
+// mount the reactive version in its place.
+if (typeof document !== 'undefined') {
+  const mount = document.querySelector('[data-azox-root]') ?? document.body;
+  mount.innerHTML = '';
+  render(mount);
+}
+`.trimStart();
+}
+
+function emitNode(node, statements, fallbackVar) {
+  if (!node) return 'null';
+
+  if (node.type === 'text') {
+    return emitText(node, statements, fallbackVar);
+  }
+
+  // A fragment (from <slot />) has no element of its own; it wraps
+  // its children in a DocumentFragment so they land in the parent.
+  if (node.type === 'fragment') {
+    const varName = nextId();
+    statements.push(`const ${varName} = document.createDocumentFragment();`);
+    appendChildren(varName, node.children, statements, fallbackVar);
+    return varName;
+  }
+
+  const varName = nextId();
+  statements.push(`const ${varName} = document.createElement(${JSON.stringify(node.name)});`);
+
+  for (const [key, attr] of Object.entries(node.attrs)) {
+    emitAttr(varName, key, attr, statements);
+  }
+
+  appendChildren(varName, node.children, statements, fallbackVar);
+
+  return varName;
+}
+
+function appendChildren(parentVar, children, statements, fallbackVar) {
+  for (const child of children) {
+    const childVar = emitNode(child, statements, fallbackVar);
+    if (childVar !== 'null') statements.push(`${parentVar}.appendChild(${childVar});`);
+  }
+}
+
+function emitText(node, statements, fallbackVar) {
+  // Purely static text: one text node, no effect needed.
+  if (node.parts.every((p) => p.kind === 'static')) {
+    const value = node.parts.map((p) => p.value).join('');
+    const varName = nextId();
+    statements.push(`const ${varName} = document.createTextNode(${JSON.stringify(value)});`);
+    return varName;
+  }
+
+  // Dynamic text: one text node, one effect that rewrites its data.
+  const varName = nextId();
+  statements.push(`const ${varName} = document.createTextNode('');`);
+  const expr = node.parts
+    .map((p) => (p.kind === 'static' ? JSON.stringify(p.value) : `String(${p.expr})`))
+    .join(' + ');
+  statements.push(`effect(() => { ${varName}.data = ${expr}; });`);
+  return varName;
+}
+
+function emitAttr(varName, key, attr, statements) {
+  if (key.startsWith('on:')) {
+    const event = key.slice(3);
+    statements.push(`${varName}.addEventListener(${JSON.stringify(event)}, ${attr.expr});`);
+    return;
+  }
+
+  if (attr.kind === 'static') {
+    statements.push(`${varName}.setAttribute(${JSON.stringify(key)}, ${JSON.stringify(attr.value)});`);
+    return;
+  }
+
+  // Dynamic attribute: wrap in its own effect, same fine-grained rule as text.
+  statements.push(`effect(() => { ${varName}.setAttribute(${JSON.stringify(key)}, String(${attr.expr})); });`);
+}
+
+// Component imports are resolved at build time and inlined, so the
+// .azox specifier must not survive into JavaScript the browser loads.
+function dropComponentImports(script) {
+  return script.replace(/^\s*import\s+[A-Z]\w*\s+from\s+['"][^'"]+\.azox['"]\s*;?\s*$/gm, '');
+}
+
+// Rewrites every relative import specifier in the user's <script>
+// block so it still resolves once the module lives in outPath
+// instead of next to sourceDir.
+function rebaseImports(script, sourceDir, outPath) {
+  return script.replace(
+    /(from\s+|import\s+)(['"])(\.[^'"]*)\2/g,
+    (full, keyword, quote, specifier) =>
+      `${keyword}${quote}${rebaseSpecifier(resolve(sourceDir, specifier), outPath)}${quote}`
+  );
+}
+
+// Re-expresses an absolute target path as a path relative to outPath.
+function rebaseSpecifier(absoluteTarget, outPath) {
+  let rebased = relative(dirname(outPath), absoluteTarget);
+  if (!rebased.startsWith('.')) rebased = `./${rebased}`;
+  return rebased;
+}

package/core/compiler/index.js

@@ -0,0 +1,4 @@
+// Public entry point for `import ... from 'azoxjs/compiler'`.
+
+export { parseAzox } from './parser.js';
+export { compileToModule } from './compileToJs.js';