@ankhorage/devtools 1.10.10 → 1.10.12

package/dist/tools/skills/assets/zora-designer/scripts/scaffold-template.mjs

@@ -1,22 +1,20 @@
 #!/usr/bin/env bun
 
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import { generateTemplateCatalog } from './generate-template-catalog.mjs';
 import { loadOwnerApis } from './owner-api.mjs';
 
-/*** Validate and scaffold one ready authored manifest into the normal Templates variant layout. */
+/*** Scaffold one complete portable template and refresh filesystem discovery. */
 export async function scaffoldTemplate(input) {
   assertRecord(input, 'Scaffold input');
-  for (const field of ['targetDirectory', 'category', 'templateId', 'label', 'description']) {
+  for (const field of ['targetDirectory', 'category', 'slug']) {
     assertNonEmptyString(input[field], field);
   }
-  if (
-    !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(input.templateId) ||
-    ['default', 'starter'].includes(input.templateId)
-  ) {
-    throw new Error('templateId must be a non-reserved kebab-case identifier.');
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(input.slug)) {
+    throw new Error('slug must be a kebab-case identifier.');
   }
   assertRecord(input.manifest, 'manifest');
 
@@ -30,165 +28,85 @@ export async function scaffoldTemplate(input) {
   if (input.manifest.metadata?.category !== input.category) {
     throw new Error('Scaffold category must match manifest.metadata.category.');
   }
+  if (input.manifest.metadata?.slug !== input.slug) {
+    throw new Error('Scaffold slug must match manifest.metadata.slug.');
+  }
 
   const owners = await loadOwnerApis(targetDirectory);
   const composition = owners.templates.validateTemplateManifest(input.manifest, 'release');
-  if (composition.status !== 'ready') {
-    throw new Error(
-      `Manifest is not release-ready: ${composition.diagnostics.map((item) => item.message).join('; ')}`,
-    );
-  }
   const manifest = owners.templates.assertTemplateManifestReady(composition);
-  const categoryDirectoryName = input.category.replaceAll('_', '-');
+
   const categoryDirectory = resolve(
     targetDirectory,
-    'src/templates/starter/categories',
-    categoryDirectoryName,
+    'src/templates/categories',
+    input.category.replaceAll('_', '-'),
   );
   assertInside(targetDirectory, categoryDirectory);
-  const variantDirectory = resolve(categoryDirectory, input.templateId);
-  assertInside(categoryDirectory, variantDirectory);
-  if (await pathExists(variantDirectory)) {
+
+  const templateDirectory = resolve(categoryDirectory, input.slug);
+  assertInside(categoryDirectory, templateDirectory);
+  if (await pathExists(templateDirectory)) {
     throw new Error(
-      `Template source already exists: ${relative(targetDirectory, variantDirectory)}`,
+      `Template source already exists: ${relative(targetDirectory, templateDirectory)}`,
     );
   }
 
-  const registryPath = join(categoryDirectory, 'index.ts');
-  const registrySource = await readFile(registryPath, 'utf8');
-  const symbol = toPascalCase(input.templateId);
-  const factoryBase = symbol.endsWith('Starter') ? symbol.slice(0, -'Starter'.length) : symbol;
-  const factoryName = `create${factoryBase}StarterTemplate`;
-  const manifestName = `AUTHORED_${toConstantCase(input.templateId)}_MANIFEST`;
-  const registrySourceUpdated = updateCategoryRegistry(registrySource, {
-    templateId: input.templateId,
-    label: input.label,
-    description: input.description,
-    factoryName,
-  });
-  const files = createTemplateFiles({ manifest, manifestName, factoryName });
-
-  await mkdir(variantDirectory, { recursive: true });
-  for (const [fileName, contents] of Object.entries(files)) {
-    await writeFile(join(variantDirectory, fileName), contents);
-  }
-  await writeFile(registryPath, registrySourceUpdated);
+  const screensDirectory = join(templateDirectory, 'assets', 'screens');
+  const imagesDirectory = join(templateDirectory, 'assets', 'images');
+  await mkdir(screensDirectory, { recursive: true });
+  await mkdir(imagesDirectory, { recursive: true });
+  await writeFile(
+    join(templateDirectory, 'createAppManifest.ts'),
+    createManifestSource(manifest),
+    'utf8',
+  );
+  await rm(join(categoryDirectory, '.gitkeep'), { force: true });
+  await generateTemplateCatalog(targetDirectory, owners.contracts.APP_CATEGORIES);
 
   return {
     targetDirectory,
-    registryPath: relative(targetDirectory, registryPath),
-    createdFiles: Object.keys(files).map((fileName) =>
-      relative(targetDirectory, join(variantDirectory, fileName)),
-    ),
-    factoryName,
+    templateDirectory: relative(targetDirectory, templateDirectory),
+    createdFiles: [relative(targetDirectory, join(templateDirectory, 'createAppManifest.ts'))],
+    assetDirectories: [
+      relative(targetDirectory, screensDirectory),
+      relative(targetDirectory, imagesDirectory),
+    ],
   };
 }
 
-/*** Create normal manifest, factory, and entrypoint source for one authored starter variant. */
-function createTemplateFiles({ manifest, manifestName, factoryName }) {
-  const manifestSource = `import type { AppManifest } from '@ankhorage/contracts';
-
-export const ${manifestName} = ${JSON.stringify(manifest, null, 2)} satisfies AppManifest;
-`;
-  const templateSource = `import type { AppManifest } from '@ankhorage/contracts';
+/*** Serialize one complete manifest as the template's canonical default export. */
+function createManifestSource(manifest) {
+  return `import type { AppManifest } from '@ankhorage/contracts';
 
-import type { TemplateSeed } from '../../../starter.types';
-import { ${manifestName} } from './manifest';
+const manifest = ${JSON.stringify(manifest, null, 2)} satisfies AppManifest;
 
-/*** Create the authored starter while applying the caller's canonical app identity and theme. */
-export function ${factoryName}(seed: TemplateSeed): AppManifest {
-  const theme = seed.theme ?? ${manifestName}.themes[0];
-  if (theme === undefined) {
-    throw new Error('The authored template requires one resolved theme.');
-  }
-  return {
-    ...${manifestName},
-    metadata: {
-      ...${manifestName}.metadata,
-      name: seed.appName,
-      slug: seed.slug,
-      version: seed.version ?? ${manifestName}.metadata.version,
-      themeId: theme.id,
-    },
-    themes: [theme],
-    activeThemeId: theme.id,
-  };
+/*** Create the complete portable application manifest for this template. */
+export default function createAppManifest(): AppManifest {
+  return structuredClone(manifest);
 }
 `;
-  return {
-    'index.ts': `export { ${factoryName} } from './template';\n`,
-    'manifest.ts': manifestSource,
-    'template.ts': templateSource,
-  };
-}
-
-/*** Add one stable import and definition to an existing category registry. */
-function updateCategoryRegistry(source, definition) {
-  const importLine = `import { ${definition.factoryName} } from './${definition.templateId}';`;
-  if (source.includes(`id: '${definition.templateId}'`) || source.includes(importLine)) {
-    throw new Error(`Template is already registered: ${definition.templateId}`);
-  }
-  const exportMarker = '\nexport const ';
-  const exportIndex = source.indexOf(exportMarker);
-  if (exportIndex < 0) {
-    throw new Error('Category registry does not expose its canonical template array.');
-  }
-  const prefixLines = source.slice(0, exportIndex).trimEnd().split('\n');
-  const relativeImports = [
-    ...prefixLines.filter((line) => /^import .* from '\.\//u.test(line)),
-    importLine,
-  ].sort((left, right) => left.localeCompare(right));
-  const preservedPrefix = prefixLines.filter((line) => !/^import .* from '\.\//u.test(line));
-  const withImport = `${[...preservedPrefix, ...relativeImports].join('\n')}\n${source.slice(exportIndex + 1)}`;
-  const closeMarker = '] satisfies readonly CategoryStarterTemplateDefinition[];';
-  const closeIndex = withImport.indexOf(closeMarker);
-  if (closeIndex < 0) {
-    throw new Error('Category registry is missing its canonical definition-array terminator.');
-  }
-  const entry = `  {
-    id: '${escapeSingleQuoted(definition.templateId)}',
-    label: '${escapeSingleQuoted(definition.label)}',
-    description: '${escapeSingleQuoted(definition.description)}',
-    create: ${definition.factoryName},
-  },
-`;
-  return `${withImport.slice(0, closeIndex)}${entry}${withImport.slice(closeIndex)}`;
-}
-
-/*** Convert kebab-case identifiers to a PascalCase source symbol. */
-function toPascalCase(value) {
-  return value
-    .split('-')
-    .map((segment) => segment[0].toUpperCase() + segment.slice(1))
-    .join('');
-}
-
-/*** Convert kebab-case identifiers to an uppercase constant name. */
-function toConstantCase(value) {
-  return value.replaceAll('-', '_').toUpperCase();
-}
-
-/*** Escape content placed in generated single-quoted TypeScript strings. */
-function escapeSingleQuoted(value) {
-  return value.replaceAll('\\', '\\\\').replaceAll("'", "\\'");
 }
 
 /*** Assert that a resolved output remains inside its declared owner directory. */
-function assertInside(parentDirectory, childPath) {
-  const relativePath = relative(parentDirectory, childPath);
-  if (relativePath === '' || relativePath.startsWith(`..${sep}`) || relativePath === '..') {
-    throw new Error(`Scaffold path escapes its owner directory: ${childPath}`);
+function assertInside(parentPath, childPath) {
+  const relativePath = relative(parentPath, childPath);
+  if (
+    relativePath === '' ||
+    relativePath === '..' ||
+    relativePath.startsWith(`..${sep}`) ||
+    relativePath.startsWith('../')
+  ) {
+    throw new Error(`Template path escapes its owner directory: ${childPath}`);
   }
 }
 
-/*** Return whether a filesystem path already exists. */
-async function pathExists(path) {
+/*** Return whether a filesystem path exists. */
+async function pathExists(filePath) {
   try {
-    await access(path);
+    await access(filePath);
     return true;
-  } catch (error) {
-    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return false;
-    throw error;
+  } catch {
+    return false;
   }
 }
 
@@ -209,8 +127,10 @@ function assertNonEmptyString(value, label) {
 /*** Run deterministic Templates source scaffolding from one JSON input. */
 async function main() {
   const [inputPath] = process.argv.slice(2);
-  if (!inputPath) throw new Error('Usage: scaffold-template.mjs <scaffold-input.json>');
-  const input = JSON.parse(await readFile(inputPath, 'utf8'));
+  if (!inputPath) {
+    throw new Error('Usage: scaffold-template.mjs <scaffold-input.json>');
+  }
+  const input = JSON.parse(await readFile(resolve(inputPath), 'utf8'));
   console.log(JSON.stringify(await scaffoldTemplate(input), null, 2));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.10.10",
+  "version": "1.10.12",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -105,9 +105,9 @@
     "version-packages": "bun src/cli/bin/changeset.ts version"
   },
   "dependencies": {
-    "@ankhorage/utility": "^0.2.0",
+    "@ankhorage/utility": "^0.3.0",
     "@changesets/cli": "^3.0.1",
-    "@eslint/compat": "^2.1.0",
+    "@eslint/compat": "^2.1.1",
     "@eslint/js": "^10.0.1",
     "eslint": "^10.9.1",
     "eslint-config-prettier": "^10.1.8",

package/dist/tools/skills/assets/ankhorage-project-structure/references/expo-apps.md

@@ -1,43 +0,0 @@
-# Expo and React Native Applications
-
-An Expo application is an independently installable application and may use ports-and-adapters
-principles for its application behavior. Expo Router route files are framework-owned inbound
-adapters, not the home of domain logic.
-
-## Structure
-
-```text
-app/                         # Expo Router route tree
-src/
-  app/                       # providers and app composition
-  <domain>/                  # application-owned domains
-    domain/
-    application/
-    ports/
-  platform/                  # app-local native/web adapters only
-  utils/                     # app-wide internal utilities
-```
-
-Keep route files thin: resolve route parameters and navigation context, invoke or render the owning
-application boundary, and declare route-specific framework configuration. Substantial UI belongs
-with its owning domain or reusable UI package.
-
-## Ankhorage ownership
-
-- Use Contracts for portable authored state.
-- Use Runtime for manifest/action/data execution.
-- Use ZORA and Surface for reusable UI.
-- Use Expo Runtime and provider packages for platform integration.
-- Do not copy package behavior into the generated app merely to avoid a public API or release.
-- Do not import Studio source or rely on the Studio workspace.
-
-## Standalone lifecycle
-
-Each generated app owns its package manifest, lockfile, installation, validation, build, and
-deployment inputs. A parent dashboard may invoke commands with the app as `cwd`, but must not
-install it through a hidden shared workspace contract.
-
-## Platform variants
-
-Use `.native`, `.web`, `.ios`, and `.android` variants only when the platform behavior genuinely
-differs. Keep the portable contract in the unsuffixed module and concrete behavior at the edge.

package/dist/tools/skills/assets/ankhorage-project-structure/references/hexagonal-architecture.md

@@ -1,120 +0,0 @@
-# Ankhorage Ports and Adapters
-
-Use ports-and-adapters principles for application, engine, service, and hybrid packages. The
-Ankhorage package is the hexagon; internal domains are not independent feature packages.
-
-## Purpose
-
-Protect stable package policy from React, Expo, HTTP, Fastify, Bun, filesystem, process, database,
-provider SDK, and test-harness details. The useful rule is dependency direction, not a mandatory
-folder ceremony.
-
-```text
-package edge / adapter -> application -> domain
-                              |
-                              v
-                         required ports
-
-concrete adapter -> required port
-```
-
-## Roles
-
-- **Domain:** pure rules, values, invariants, and deterministic transformations owned by the
-  package.
-- **Application:** command-independent use cases and orchestration of domain behavior.
-- **Port:** a capability contract required by application/domain code to reach an external edge.
-- **Inbound adapter:** converts CLI, HTTP, UI, Runtime, worker, or test input into an application
-  invocation.
-- **Outbound adapter:** implements a required port using filesystem, process, provider, storage,
-  network, Expo, or another package.
-- **Composition:** selects implementations and wires adapters to application operations.
-
-Ports belong beside the application/domain code that needs them. Do not create a global
-`src/ports/` dumping ground.
-
-## Package-level edges
-
-Ankhorage preserves recognizable package edges:
-
-```text
-src/app/       React or React Native composition and package-wide UI entrypoints
-src/cli/       one package-level Ankh provider
-src/host/      Bun/Node/Fastify/filesystem composition and shared host infrastructure
-src/platform/  native, web, Expo, or provider-specific implementations
-```
-
-Internal domain behavior must not migrate into these directories merely because an adapter calls
-it. Edges translate and compose; domains own behavior.
-
-## Domain-first organization
-
-Substantial domains may use role directories:
-
-```text
-src/
-  projects/
-    contracts/
-    domain/
-    application/
-    ports/
-  deploy/
-    contracts/
-    domain/
-    application/
-    ports/
-```
-
-Small domains remain flat while their siblings have the same role. Introduce role directories
-when definitions, parsers, use cases, adapters, or utilities begin mixing at one level.
-
-Do not use:
-
-```text
-src/features/
-src/common/
-src/core/
-src/shared/
-src/ports/
-```
-
-unless a repository has an explicit, narrower meaning that cannot be represented by an owning
-domain or package edge.
-
-## When a port is justified
-
-Create a port when at least one is true:
-
-- more than one real adapter exists or is planned by current architecture;
-- deterministic tests need to replace a side effect;
-- the dependency is volatile or provider-specific;
-- the same application operation is invoked through multiple inbound edges;
-- the capability crosses a package, process, storage, network, platform, or credential boundary.
-
-Do not create a port merely because a function calls another function. Pure utilities, component
-composition, value transformations, and React-local presentation state usually do not need ports.
-
-## React and React Native
-
-React/RN UI is an inbound edge. Components may collect input, render state, and invoke application
-actions. Provider execution and durable business rules remain outside components and hooks.
-
-- Keep navigation route modules thin.
-- Keep UI-specific transient state near the UI.
-- Move reusable business decisions and cross-interface operations into the owning domain or
-  application layer.
-- Inject values, callbacks, or capability interfaces into reusable UI rather than importing
-  concrete providers.
-
-## Composition roots
-
-Keep wiring explicit and limited to package entrypoints such as app startup, host creation, CLI
-provider construction, or a focused factory. Do not use ambient service locators or hidden mutable
-registries as dependency injection.
-
-## Testing
-
-- Test domain and application behavior with deterministic inputs and fake ports.
-- Test concrete adapters against their real protocol boundary.
-- Test user-facing flows through inbound edges only where the integration adds evidence.
-- Do not duplicate the full acceptance matrix for every internal refactor.

package/dist/tools/skills/assets/ankhorage-project-structure/references/repository-profiles.md

@@ -1,91 +0,0 @@
-# Repository Profiles
-
-Select one primary profile from the repository's actual ownership and consumers. A package may
-also expose secondary edges such as CLI or Expo without changing its primary profile.
-
-## Application, engine, or hybrid
-
-Use for packages that coordinate use cases, state transitions, external systems, or several
-delivery mechanisms.
-
-Typical structure:
-
-```text
-src/
-  index.ts
-  <domain>/
-    contracts/
-    domain/
-    application/
-    ports/
-  app/                 # optional React/RN edge and composition
-  cli/                 # optional package-level Ankh edge
-  host/                # optional Bun/Node/HTTP/filesystem edge
-  platform/            # optional native/web/provider edge
-  utils/               # internal cross-domain utilities only
-```
-
-Create role subdirectories only when a domain has enough distinct responsibilities to need them.
-Do not pre-create empty `contracts`, `domain`, `application`, or `ports` directories.
-
-## Contracts or value library
-
-Contracts own portable shape and structural validation, not provider execution.
-
-```text
-src/
-  index.ts
-  <domain>/
-    contracts/
-    parsers/
-    constants/
-    tests colocated with their owner
-```
-
-- Keep modules deterministic and side-effect free.
-- Type definitions and structural parsers change together.
-- Provider readiness, network state, filesystem state, and UI behavior stay in their owner.
-- Avoid `Record<string, unknown>` escape hatches when a canonical concept can be modeled.
-
-## Platform or provider adapter
-
-These packages deliberately implement an external technology boundary.
-
-```text
-src/
-  index.ts
-  contracts/           # provider-facing public configuration when owned here
-  planning/            # pure capability/configuration planning
-  adapters/            # concrete provider/platform implementations
-  composition/         # factories or provider registration
-  cli/                 # only when this package exposes Ankh commands
-```
-
-- Depend on portable contracts or ports from lower-level owning packages.
-- Do not redefine the application/domain model locally.
-- Keep provider SDK values from leaking through portable public contracts.
-- Separate build-time planning from runtime execution when both exist.
-
-## Tooling package
-
-Tooling packages may be command-centric but still keep parsing, policy, and side effects distinct.
-
-```text
-src/
-  cli/
-  policy/              # deterministic rules and diagnostics
-  application/         # command-independent operations
-  adapters/            # filesystem, process, GitHub, registry, etc.
-  composition/
-  index.ts
-```
-
-The package remains the boundary. Do not create internal pseudo-packages beneath `features/`.
-
-## Generated or standalone application
-
-A generated application is an independently installable and buildable project. It is not a
-workspace child of Studio and must not depend on Studio-local source or installation state.
-
-Use the Expo application profile when applicable. Application-specific domains live under `src/`;
-route entrypoints remain thin.

package/dist/tools/skills/assets/ankhorage-project-structure/references/ui-libraries.md

@@ -1,79 +0,0 @@
-# UI and Design-System Libraries
-
-ZORA and Surface are layered reusable UI libraries, not hexagonal applications. From an
-application's perspective, they help build the inbound UI adapter; internally they use component
-ownership and dependency direction rather than application ports and use cases.
-
-## Recommended layers
-
-```text
-src/
-  foundation/
-  theme/
-  layout/
-  primitives/
-  components/
-  patterns/
-  registry/
-  internal/
-  index.ts
-```
-
-Use only the layers owned by the package. Surface and ZORA must not duplicate the same abstraction.
-
-Dependency direction moves from composed UI toward stable foundations:
-
-```text
-patterns -> components -> primitives/foundation
-patterns -> layout -> foundation
-components -> theme -> foundation
-registry -> component/pattern metadata
-```
-
-Lower layers do not import higher layers. Components do not import the global registry.
-
-## Component ownership
-
-Colocate artifacts that change with the component:
-
-```text
-components/
-  Button/
-    Button.tsx
-    Button.types.ts
-    Button.metadata.ts
-    Button.test.tsx
-```
-
-Keep a component as a single file while it has one homogeneous responsibility. Introduce its
-directory when tests, metadata, platform variants, styles, or private helpers justify it.
-
-Component-specific authoring metadata belongs beside the component. Registry composition may be
-central, but metadata must not become a parallel model detached from implementation and props.
-
-## Patterns
-
-Patterns are reusable UI solutions, not application use cases. Group substantial collections by
-UI capability:
-
-```text
-patterns/
-  auth/
-  content/
-  navigation/
-  onboarding/
-  settings/
-```
-
-A pattern may accept state, values, errors, and callbacks. It must not execute Supabase, HTTP,
-filesystem, deployment, or application authorization behavior.
-
-## Platform behavior
-
-Keep provider and platform execution in the owning adapter package unless it is an unavoidable
-peer-backed UI implementation. Prefer injected values/callbacks and platform-neutral component
-contracts. Expo Runtime and provider packages own application/platform integration.
-
-Do not introduce `domain`, `application`, `ports`, or `adapters` for ordinary components. A complex
-subsystem such as an editor, canvas, or data grid may use internal model/platform boundaries when
-real complexity warrants them.