@auraindustry/aurajs 0.0.7 → 0.1.1

package/src/commands/project-authoring.mjs

@@ -0,0 +1,454 @@
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+import {
+  scaffold,
+  scaffoldGame,
+  listCreateTemplates,
+  listCreateTemplateAliasHints,
+  normalizeCreateTemplate,
+} from '../scaffold.mjs';
+import { importThreeJsProject, parseFromArgs } from '../project-importer.mjs';
+import { generateProjectFiles, listMakeKinds, listProjectMakeCatalog, listProjectMakeKinds } from '../make.mjs';
+import {
+  CANONICAL_PREFAB_ROLES,
+  runProjectCheck,
+  runProjectExplain,
+} from '../authored-project.mjs';
+import {
+  canPromptInteractively,
+  printBanner,
+  printSection,
+  promptInput,
+  promptSelect,
+} from '../terminal-ui.mjs';
+
+export const CREATE_TEMPLATE_OPTION_LIST = listCreateTemplates().join('|');
+export const CREATE_TEMPLATE_ALIAS_HINT_LIST = listCreateTemplateAliasHints().join(', ');
+export const CREATE_USAGE = `aura create <name> [--template <${CREATE_TEMPLATE_OPTION_LIST}>] [--skip-install]`;
+export const FROM_USAGE = 'aura from <source-path> --source threejs [--out <path>] [--name <name>] [--scene <path>] [--skip-install]';
+export const MAKE_KIND_OPTION_LIST = listMakeKinds().join('|');
+export const PREFAB_ROLE_OPTION_LIST = CANONICAL_PREFAB_ROLES.join('|');
+export const MAKE_USAGE = `aura make <${MAKE_KIND_OPTION_LIST}> <name> [--role <${PREFAB_ROLE_OPTION_LIST}>]`;
+export const MAKE_SUPPORTED_KINDS_HELP_TEXT = listMakeKinds().join(', ');
+
+function raiseCliError(errorHandler, message) {
+  if (typeof errorHandler === 'function') {
+    errorHandler(message);
+    return;
+  }
+  throw new Error(message);
+}
+
+function handleProjectAuthoringError(errorHandler, err) {
+  raiseCliError(errorHandler, err instanceof Error ? err.message : String(err));
+}
+
+export function parseCreateArgs(args) {
+  const allowedTemplates = new Set(listCreateTemplates());
+  let name = null;
+  let template = '2d-adventure';
+  let skipInstall = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--template') {
+      if (!args[i + 1]) {
+        throw new Error('Missing value for --template.');
+      }
+      template = String(args[i + 1]).toLowerCase();
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--template=')) {
+      template = arg.slice('--template='.length).toLowerCase();
+      continue;
+    }
+    if (arg === '--skip-install' || arg === '--no-install') {
+      skipInstall = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      throw new Error(`Unknown option for create: ${arg}`);
+    }
+    if (name !== null) {
+      throw new Error(`Unexpected extra argument "${arg}". Usage: ${CREATE_USAGE}`);
+    }
+    name = arg;
+  }
+
+  const normalizedTemplate = normalizeCreateTemplate(template);
+  if (!normalizedTemplate || !allowedTemplates.has(normalizedTemplate)) {
+    throw new Error(`Invalid --template "${template}". Supported templates: ${[...allowedTemplates].join(', ')} (aliases: ${CREATE_TEMPLATE_ALIAS_HINT_LIST}).`);
+  }
+
+  return { name, template: normalizedTemplate, skipInstall };
+}
+
+export function parseMakeArgs(args, { cwd = process.cwd() } = {}) {
+  let allowedKinds = null;
+  try {
+    allowedKinds = new Set(listProjectMakeKinds({ cwd }));
+  } catch {
+    allowedKinds = new Set(listMakeKinds());
+  }
+  let kind = null;
+  let name = null;
+  let role = null;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--role') {
+      const value = args[i + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`Missing value for --role. Usage: ${MAKE_USAGE}`);
+      }
+      role = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--role=')) {
+      role = arg.slice('--role='.length);
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      throw new Error(`Unknown option for make: ${arg}`);
+    }
+    if (kind === null) {
+      kind = arg;
+      continue;
+    }
+    if (name === null) {
+      name = arg;
+      continue;
+    }
+    throw new Error(`Unexpected extra argument "${arg}". Usage: ${MAKE_USAGE}`);
+  }
+
+  if (!kind) {
+    throw new Error(`Missing file kind. Usage: ${MAKE_USAGE}`);
+  }
+  if (!allowedKinds.has(kind)) {
+    throw new Error(`Invalid make kind "${kind}". Supported kinds: ${[...allowedKinds].join(', ')}.`);
+  }
+  if (!name) {
+    throw new Error(`Missing file name. Usage: ${MAKE_USAGE}`);
+  }
+  if (role !== null && kind !== 'prefab') {
+    throw new Error('`--role` is only supported for `aura make prefab`.');
+  }
+
+  return { kind, name, role };
+}
+
+function toMakeKindLabel(entry) {
+  const baseLabel = String(entry?.id || '')
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+  if (entry?.owner === 'core') {
+    return baseLabel;
+  }
+  return `${baseLabel} [${entry.owner}]`;
+}
+
+export async function promptForMakeArgs({
+  cwd = process.cwd(),
+  catalogRoot = null,
+  promptSelectImpl = promptSelect,
+  promptInputImpl = promptInput,
+  printBannerImpl = printBanner,
+  printSectionImpl = printSection,
+} = {}) {
+  const catalog = listProjectMakeCatalog({ cwd, catalogRoot });
+  if (!Array.isArray(catalog) || catalog.length === 0) {
+    throw new Error('No make kinds are available for the current AuraJS project.');
+  }
+
+  const defaultKind = catalog.some((entry) => entry.id === 'scene')
+    ? 'scene'
+    : catalog[0].id;
+
+  printBannerImpl('MAKE');
+  printSectionImpl('AuraJS Make', 'Choose what to generate in the current project.');
+
+  const kind = await promptSelectImpl(
+    '  What do you want to make?',
+    catalog.map((entry) => ({
+      value: entry.id,
+      label: toMakeKindLabel(entry),
+    })),
+    defaultKind,
+  );
+
+  let name = '';
+  while (!name) {
+    name = await promptInputImpl('  What should it be called');
+    if (!name) {
+      console.log('  Name is required.');
+    }
+  }
+
+  return parseMakeArgs([kind, name], { cwd });
+}
+
+export function parseSimpleJsonFlag(args, commandName) {
+  let json = false;
+  for (const arg of args) {
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      throw new Error(`Unknown option for ${commandName}: ${arg}`);
+    }
+    throw new Error(`Unexpected extra argument "${arg}". Usage: aura ${commandName} [--json]`);
+  }
+  return { json };
+}
+
+export async function cmdInit(args, { error } = {}) {
+  const name = args[0];
+  if (!name) {
+    raiseCliError(error, 'Missing project name. Usage: aura init <name>');
+  }
+
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    raiseCliError(error, 'Project name must contain only letters, numbers, hyphens, and underscores.');
+  }
+
+  const dest = resolve(process.cwd(), name);
+
+  try {
+    printBanner('CREATE');
+    printSection('AuraJS Create', `Scaffolding ${name}...`);
+    const result = scaffold(name, dest);
+    console.log(`\n  Created "${name}" at ${dest}`);
+    console.log('');
+    for (const file of result.files) {
+      console.log(`    ${file}`);
+    }
+    console.log('');
+    console.log('  Get started:');
+    console.log(`    cd ${name}`);
+    console.log('    aura dev');
+    console.log('');
+    console.log('  Docs:');
+    console.log('    https://www.aurajs.gg/docs');
+    console.log('');
+    console.log('  Agent skills:');
+    console.log('    cd <your-codebase>');
+    console.log('    npx -y skills add Aura-Industry/auramaxx');
+    console.log('');
+  } catch (err) {
+    handleProjectAuthoringError(error, err);
+  }
+}
+
+export async function cmdCreate(args, { error } = {}) {
+  const parsed = parseCreateArgs(args);
+  if (!parsed.name) {
+    raiseCliError(error, `Missing project name. Usage: ${CREATE_USAGE}`);
+  }
+
+  const name = parsed.name;
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    raiseCliError(error, 'Project name must contain only letters, numbers, hyphens, and underscores.');
+  }
+
+  const dest = resolve(process.cwd(), name);
+
+  try {
+    printBanner('CREATE');
+    printSection('AuraJS Create', `Scaffolding ${name}...`);
+    const result = scaffoldGame({
+      name,
+      dest,
+      template: parsed.template,
+    });
+
+    console.log(`\n  Created "${name}" at ${dest}`);
+    console.log(`  Template: ${result.template}`);
+    console.log('');
+    for (const file of result.files) {
+      console.log(`    ${file}`);
+    }
+    console.log('');
+
+    if (parsed.skipInstall) {
+      console.log('  Skipped npm install (--skip-install).');
+      console.log('');
+    } else {
+      console.log('  Installing dependencies...');
+      const install = spawnSync('npm', ['install'], {
+        cwd: dest,
+        stdio: 'inherit',
+      });
+      if (install.error || install.status !== 0) {
+        console.log('  npm install did not complete successfully. Run it manually in the project directory.');
+      }
+      console.log('');
+    }
+
+    console.log('  Get started:');
+    console.log(`    cd ${name}`);
+    if (result.runtimeFamily === 'retro') {
+      console.log('    npm run retro:check');
+      console.log('    npm run build:gbc');
+    } else {
+      console.log('    npm run dev');
+      console.log('');
+      console.log('  Optional packaged local run:');
+      console.log('    npm run play');
+    }
+    console.log('');
+    console.log('  Docs:');
+    console.log('    https://www.aurajs.gg/docs');
+    console.log('');
+    console.log('  Agent skills:');
+    console.log('    cd <your-codebase>');
+    console.log('    npx -y skills add Aura-Industry/auramaxx');
+    console.log('');
+  } catch (err) {
+    handleProjectAuthoringError(error, err);
+  }
+}
+
+export async function cmdFrom(args, { error } = {}) {
+  let parsed;
+  try {
+    parsed = parseFromArgs(args);
+  } catch (err) {
+    raiseCliError(error, err instanceof Error ? err.message : String(err));
+    return;
+  }
+
+  try {
+    const result = importThreeJsProject({
+      sourceRoot: parsed.sourcePath,
+      outputPath: parsed.outputPath,
+      projectName: parsed.projectName,
+      scenePath: parsed.scenePath,
+    });
+
+    console.log(`\n  Imported "${parsed.sourcePath}" into ${result.outputRoot}`);
+    console.log('  Source type: threejs');
+    console.log(`  Project name: ${result.projectName}`);
+    if (result.report.sceneImport.outputScenePath) {
+      console.log(`  Scene: ${result.report.sceneImport.outputScenePath}`);
+    } else {
+      console.log('  Scene: none detected');
+    }
+    console.log(`  Report: ${result.reportPath}`);
+    console.log('');
+
+    if (parsed.skipInstall) {
+      console.log('  Skipped npm install (--skip-install).');
+      console.log('');
+    } else {
+      console.log('  Installing dependencies...');
+      const install = spawnSync('npm', ['install'], {
+        cwd: result.outputRoot,
+        stdio: 'inherit',
+      });
+      if (install.error || install.status !== 0) {
+        console.log('  npm install did not complete successfully. Run it manually in the generated project directory.');
+      }
+      console.log('');
+    }
+
+    console.log('  Next:');
+    console.log(`    cd ${result.outputRoot}`);
+    console.log('    npm run dev');
+    console.log('');
+  } catch (err) {
+    handleProjectAuthoringError(error, err);
+  }
+}
+
+export async function cmdMake(args, { error } = {}) {
+  try {
+    if (args[0] === 'list') {
+      const parsed = parseSimpleJsonFlag(args.slice(1), 'make list');
+      const catalog = listProjectMakeCatalog({ cwd: process.cwd() });
+      if (parsed.json) {
+        process.stdout.write(`${JSON.stringify({
+          schema: 'aurajs.make-catalog.v1',
+          projectRoot: process.cwd(),
+          kinds: catalog.map((entry) => ({
+            id: entry.id,
+            owner: entry.owner,
+            scope: entry.scope,
+          })),
+        }, null, 2)}\n`);
+        return;
+      }
+      console.log('');
+      console.log('  Available make kinds');
+      console.log('');
+      for (const entry of catalog) {
+        const ownerLabel = entry.owner === 'core' ? 'core' : entry.owner;
+        console.log(`    ${entry.id}  [${ownerLabel}]`);
+      }
+      console.log('');
+      return;
+    }
+    const parsed = args.length === 0 && canPromptInteractively()
+      ? await promptForMakeArgs({ cwd: process.cwd() })
+      : parseMakeArgs(args, { cwd: process.cwd() });
+    const result = await generateProjectFiles({
+      cwd: process.cwd(),
+      kind: parsed.kind,
+      name: parsed.name,
+      role: parsed.role,
+    });
+
+    console.log('');
+    console.log(`  Created ${result.kind} "${result.title}"`);
+    console.log('');
+    for (const file of result.files) {
+      console.log(`    ${file}`);
+    }
+    if (result.registration?.changed) {
+      console.log('');
+      console.log('  Updated authored registry');
+      console.log('');
+      console.log(`    ${result.registration.registryPath}`);
+      console.log(`    ${result.registration.sceneRegistryPath}`);
+    }
+    console.log('');
+  } catch (err) {
+    handleProjectAuthoringError(error, err);
+  }
+}
+
+export async function cmdExplain(args, { error } = {}) {
+  try {
+    const parsed = parseSimpleJsonFlag(args, 'explain');
+    const result = await runProjectExplain({
+      projectRoot: process.cwd(),
+      json: parsed.json,
+    });
+    process.stdout.write(result.text);
+  } catch (err) {
+    handleProjectAuthoringError(error, err);
+  }
+}
+
+export async function cmdCheck(args, { error } = {}) {
+  try {
+    const parsed = parseSimpleJsonFlag(args, 'check');
+    const result = await runProjectCheck({
+      projectRoot: process.cwd(),
+      json: parsed.json,
+    });
+    const writer = result.exitCode === 0 ? process.stdout : process.stderr;
+    writer.write(result.text);
+    if (result.exitCode !== 0) {
+      process.exit(result.exitCode);
+    }
+  } catch (err) {
+    handleProjectAuthoringError(error, err);
+  }
+}

package/src/config.mjs

@@ -168,6 +168,18 @@ const SCHEMA = {
     multiplayer: { type: 'boolean', default: false },
     steam:       { type: 'boolean', default: false },
   },
+  multiplayer: {
+    roomCode:         { type: 'string',  default: null, validate: multiplayerRoomCode },
+    roomName:         { type: 'string',  default: null, validate: nonEmptyString },
+    mode:             { type: 'enum',    default: 'local', values: ['local', 'auto', 'internet', 'relay'] },
+    relay:            { type: 'string',  default: null, validate: nonEmptyString },
+    coordinatorUrl:   { type: 'string',  default: null, validate: nonEmptyString },
+    relayUrl:         { type: 'string',  default: null, validate: nonEmptyString },
+    launcherBaseUrl:  { type: 'string',  default: null, validate: absoluteHttpUrl },
+    showDiagnostics:  { type: 'boolean', default: false },
+    chatEnabled:      { type: 'boolean', default: false },
+    chatHistoryLimit: { type: 'number',  default: 6, validate: positiveInteger },
+  },
 };
 
 // ---------------------------------------------------------------------------
@@ -215,6 +227,38 @@ function relativeAssetLikePath(value, path) {
   return null;
 }
 
+function nonEmptyString(value, path) {
+  const normalized = String(value || '').trim();
+  if (normalized.length === 0) {
+    return `${path} must be a non-empty string`;
+  }
+  return null;
+}
+
+function absoluteHttpUrl(value, path) {
+  const normalized = String(value || '').trim();
+  if (normalized.length === 0) {
+    return `${path} must be a non-empty string`;
+  }
+  try {
+    const parsed = new URL(normalized);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return `${path} must use http:// or https://, got: ${JSON.stringify(value)}`;
+    }
+    return null;
+  } catch {
+    return `${path} must be an absolute http:// or https:// URL, got: ${JSON.stringify(value)}`;
+  }
+}
+
+function multiplayerRoomCode(value, path) {
+  const normalized = String(value || '').trim();
+  if (!/^[A-Za-z0-9]{4,8}$/.test(normalized)) {
+    return `${path} must be 4-8 letters or digits, got: ${JSON.stringify(value)}`;
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Core validation + defaults
 // ---------------------------------------------------------------------------