@autoappy/cli 0.1.0-beta.0

package/README.md

@@ -0,0 +1,47 @@
+# @autoappy/cli
+
+Develop and synchronize Auto Appy applications from VS Code.
+
+> Beta contract: the CLI is implemented and locally tested, but app source pull/push requires the matching Auto Appy backend source endpoints before public use.
+
+## Start a project
+
+```bash
+mkdir my-autoappy-app
+cd my-autoappy-app
+npx @autoappy/cli init
+npm install
+npm run pull
+npm run dev
+```
+
+The starter keeps credentials in `.env` and non-secret project identity in `autoappy.json`.
+
+## Commands
+
+```text
+autoappy init
+autoappy dev
+autoappy status
+autoappy pull
+autoappy push
+autoappy code pull|push
+autoappy db pull|push
+autoappy api pull|push
+autoappy check
+```
+
+`db push` creates a reviewed backend plan and carries its token internally. It asks for one terminal confirmation; CI may use `--yes` after the Git commit has been reviewed.
+
+Database synchronization covers schema only. Customer records are never copied into the project or Git by these commands.
+
+## Required backend contract
+
+The current Auto Appy development-kit, schema and managed-API endpoints are used directly. Frontend synchronization additionally requires:
+
+```text
+GET   /api/v1/platform/organisations/{workspace}/data/apps/{app}/source
+PATCH /api/v1/platform/organisations/{workspace}/data/apps/{app}/source
+```
+
+The GET response returns `project`, `version`, `source_hash` and `status`. PATCH accepts `project`, `expected_version`, `source_hash` and `request_id`, then returns a versioned deployment receipt.

package/bin/autoappy.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2)).catch(error => {
+  console.error(`Auto Appy: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@autoappy/cli",
+  "version": "0.1.0-beta.0",
+  "description": "Develop and synchronize Auto Appy applications from VS Code.",
+  "type": "module",
+  "bin": {
+    "autoappy": "bin/autoappy.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check bin/autoappy.js && node --check src/*.js",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "autoappy",
+    "cli",
+    "low-code",
+    "deployment",
+    "vscode"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,107 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { AutoAppyClient } from './client.js';
+import { connectionEnvironment } from './env.js';
+import { hash, readConfig, readLocalProject, readState } from './files.js';
+import { initialize } from './init.js';
+import { pullCode, pullDataDefinitions, pushApis, pushCode, pushSchema } from './sync.js';
+
+function help() {
+  console.log(`Auto Appy CLI
+
+Usage: autoappy <command>
+
+  init       Create a new VS Code project
+  dev        Start the local application
+  status     Show local synchronization status
+  pull       Pull app code, database schema and APIs
+  push       Push database schema, APIs and app code
+  code pull  Pull hosted frontend files
+  code push  Push hosted frontend files
+  db pull    Pull the current database schema
+  db push    Review and apply database schema changes
+  api pull   Pull managed API definitions
+  api push   Push managed API definitions
+  check      Validate hosted frontend files
+`);
+}
+
+function context(root) {
+  const config = readConfig(root);
+  const env = connectionEnvironment(root);
+  return { config, client: new AutoAppyClient({ ...env, workspaceId: config.workspaceId, appId: config.appId }) };
+}
+
+function runLocal(binary, args, root) {
+  const command = process.platform === 'win32' ? `${binary}.cmd` : binary;
+  const filename = path.join(root, 'node_modules', '.bin', command);
+  return new Promise((resolve, reject) => {
+    const child = spawn(filename, args, { cwd: root, stdio: 'inherit' });
+    child.once('error', () => reject(new Error('Run npm install before starting local development.')));
+    child.once('exit', code => code === 0 ? resolve() : reject(new Error(`${binary} exited with status ${code}.`)));
+  });
+}
+
+export async function run(args, options = {}) {
+  const root = path.resolve(options.root || process.cwd());
+  const [command = 'help', subcommand] = args;
+  const yes = args.includes('--yes');
+  if (command === 'help' || command === '--help' || command === '-h') return help();
+  if (command === 'init') {
+    initialize(root);
+    console.log('Auto Appy project created. Fill .env and autoappy.json, run npm install, then npm run pull.');
+    return;
+  }
+  if (command === 'dev') return runLocal('vite', ['app', '--host', '127.0.0.1'], root);
+  if (command === 'check') {
+    const project = readLocalProject(root);
+    console.log(`Validated ${project.files.length} hosted frontend file(s).`);
+    return;
+  }
+  if (command === 'status') {
+    const project = readLocalProject(root);
+    const state = readState(root);
+    const changed = !state.code?.project || hash(project) !== hash(state.code.project);
+    console.log(changed ? 'Frontend: local changes' : `Frontend: synchronized at version ${state.code.version}`);
+    return;
+  }
+  const { config, client } = context(root);
+  if (command === 'code' && subcommand === 'pull') return console.log(`Pulled ${(await pullCode({ root, client })).files} frontend file(s).`);
+  if (command === 'code' && subcommand === 'push') {
+    const result = await pushCode({ root, client });
+    console.log(result.changed ? `Pushed ${result.files} frontend file(s) as version ${result.version}${result.live ? ' (live)' : ''}.` : 'Frontend is already current.');
+    return;
+  }
+  if (command === 'db' && subcommand === 'pull') {
+    const result = await pullDataDefinitions({ root, client, includeApis: false });
+    console.log(result.schema ? 'Pulled the database schema.' : 'The database schema is too large for a complete pull.');
+    return;
+  }
+  if (command === 'api' && subcommand === 'pull') {
+    const result = await pullDataDefinitions({ root, client, includeSchema: false });
+    console.log(`Pulled ${result.apis} API definition(s).`);
+    return;
+  }
+  if (command === 'db' && subcommand === 'push') {
+    const result = await pushSchema({ root, client, config, yes });
+    console.log(result.applied ? `Applied ${result.changes} database change(s).` : 'Database changes were not applied.');
+    return;
+  }
+  if (command === 'api' && subcommand === 'push') return console.log(`Saved ${(await pushApis({ root, client, config })).saved} API definition(s).`);
+  if (command === 'pull') {
+    const code = await pullCode({ root, client });
+    const definitions = await pullDataDefinitions({ root, client });
+    console.log(`Pulled ${code.files} frontend files, the database schema and ${definitions.apis} API definition(s).`);
+    return;
+  }
+  if (command === 'push') {
+    const database = await pushSchema({ root, client, config, yes });
+    if (!database.applied) return console.log('Push cancelled before any API or frontend changes.');
+    const apis = await pushApis({ root, client, config });
+    const code = await pushCode({ root, client });
+    console.log(`Push complete: ${database.changes} database change(s), ${apis.saved} API definition(s), ${code.files} frontend file(s).`);
+    return;
+  }
+  help();
+  throw new Error('Unknown command.');
+}

package/src/client.js

@@ -0,0 +1,43 @@
+export class AutoAppyClient {
+  constructor({ baseUrl, token, workspaceId, appId, fetchImpl = fetch }) {
+    this.baseUrl = baseUrl;
+    this.token = token;
+    this.workspaceId = workspaceId;
+    this.appId = appId;
+    this.fetch = fetchImpl;
+  }
+
+  path(suffix) {
+    return `${this.baseUrl}/api/v1/platform/organisations/${encodeURIComponent(this.workspaceId)}/data/${suffix.replace(/^\//, '')}`;
+  }
+
+  async request(method, suffix, body) {
+    let response;
+    try {
+      response = await this.fetch(this.path(suffix), {
+        method,
+        headers: { Accept: 'application/json', Authorization: `Bearer ${this.token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch {
+      throw new Error('Could not reach Auto Appy. Check AUTOAPPY_BASE_URL and your connection.');
+    }
+    let result;
+    try { result = await response.json(); } catch { result = null; }
+    if (!response.ok) {
+      const message = result?.message || result?.errors && Object.values(result.errors).flat()[0] || `Auto Appy request failed with HTTP ${response.status}.`;
+      const error = new Error(message);
+      error.status = response.status;
+      throw error;
+    }
+    return result?.data ?? result;
+  }
+
+  devkit() { return this.request('GET', `apps/${encodeURIComponent(this.appId)}/devkit`); }
+  source() { return this.request('GET', `apps/${encodeURIComponent(this.appId)}/source`); }
+  saveSource(payload) { return this.request('PATCH', `apps/${encodeURIComponent(this.appId)}/source`, payload); }
+  planSchema(schema) { return this.request('POST', `apps/${encodeURIComponent(this.appId)}/schema/plan`, { schema }); }
+  applySchema(token, reviewHash) { return this.request('POST', `apps/${encodeURIComponent(this.appId)}/schema/${encodeURIComponent(token)}/apply`, { review_hash: reviewHash }); }
+  createApi(payload) { return this.request('POST', 'api', payload); }
+  updateApi(id, payload) { return this.request('PATCH', `api/${encodeURIComponent(id)}`, payload); }
+}

package/src/constants.js

@@ -0,0 +1,9 @@
+export const PROJECT_FORMAT = 'autoappy.project';
+export const PROJECT_VERSION = 1;
+export const VIEW_FORMAT = 'autoappy.view-project';
+export const VIEW_VERSION = 1;
+export const STATE_FORMAT = 'autoappy.sync-state';
+export const STATE_VERSION = 1;
+export const MAX_FILES = 1200;
+export const MAX_SOURCE_BYTES = 4_000_000;
+export const ALLOWED_APP_EXTENSIONS = new Set(['.html', '.css', '.js', '.jsx', '.json', '.svg']);

package/src/env.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && ((trimmed[0] === '"' && trimmed.at(-1) === '"') || (trimmed[0] === "'" && trimmed.at(-1) === "'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+export function loadEnvironment(root) {
+  const values = { ...process.env };
+  const filename = path.join(root, '.env');
+  if (!fs.existsSync(filename)) return values;
+  for (const line of fs.readFileSync(filename, 'utf8').split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+    if (!match || values[match[1]] !== undefined) continue;
+    values[match[1]] = unquote(match[2]);
+  }
+  return values;
+}
+
+export function connectionEnvironment(root) {
+  const env = loadEnvironment(root);
+  const baseUrl = String(env.AUTOAPPY_BASE_URL || '').replace(/\/+$/, '');
+  const token = String(env.AUTOAPPY_APP_TOKEN || '');
+  if (!/^https?:\/\//.test(baseUrl)) throw new Error('Set AUTOAPPY_BASE_URL in .env. Use HTTPS outside local development.');
+  if (!token.startsWith('aa_app_')) throw new Error('Set AUTOAPPY_APP_TOKEN in .env.');
+  return { baseUrl, token };
+}

package/src/files.js

@@ -0,0 +1,118 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ALLOWED_APP_EXTENSIONS, MAX_FILES, MAX_SOURCE_BYTES, PROJECT_FORMAT, PROJECT_VERSION, STATE_FORMAT, STATE_VERSION, VIEW_FORMAT, VIEW_VERSION } from './constants.js';
+
+export const json = value => `${JSON.stringify(value, null, 2)}\n`;
+export const hash = value => crypto.createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
+
+export function assertSafeRelative(name) {
+  const parts = String(name || '').split('/');
+  const internalState = parts[0] === '.autoappy' && parts.length > 1;
+  if (!name || path.isAbsolute(name) || name.includes('\\') || parts.some((part, index) => !part || part === '.' || part === '..' || (part.startsWith('.') && !(internalState && index === 0)))) {
+    throw new Error(`Unsafe project path: ${name || '(empty)'}`);
+  }
+}
+
+export function projectFile(root, name) {
+  assertSafeRelative(name);
+  let current = root;
+  for (const part of name.split('/')) {
+    current = path.join(current, part);
+    if (!fs.existsSync(current)) continue;
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) throw new Error(`Links and special files are not supported: ${name}`);
+  }
+  return current;
+}
+
+export function readJson(filename, fallback = null) {
+  if (!fs.existsSync(filename)) return fallback;
+  return JSON.parse(fs.readFileSync(filename, 'utf8'));
+}
+
+export function writeFile(root, name, content) {
+  const filename = projectFile(root, name);
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  fs.writeFileSync(filename, content);
+}
+
+export function removeFile(root, name) {
+  const filename = projectFile(root, name);
+  if (fs.existsSync(filename)) fs.unlinkSync(filename);
+}
+
+export function readConfig(root) {
+  const filename = path.join(root, 'autoappy.json');
+  const config = readJson(filename);
+  if (!config || config.format !== PROJECT_FORMAT || config.version !== PROJECT_VERSION) throw new Error('Run autoappy init first or repair autoappy.json.');
+  if (!/^[a-f0-9-]{36}$/i.test(config.workspaceId || '') || !/^[a-f0-9-]{36}$/i.test(config.appId || '')) {
+    throw new Error('Set workspaceId and appId in autoappy.json.');
+  }
+  if (config.sourceDirectory !== 'app') throw new Error('The first CLI version requires sourceDirectory to be app.');
+  return config;
+}
+
+export function readState(root) {
+  const state = readJson(projectFile(root, '.autoappy/state.json'), { format: STATE_FORMAT, version: STATE_VERSION });
+  if (state.format !== STATE_FORMAT || state.version !== STATE_VERSION) throw new Error('Invalid .autoappy/state.json. Move it aside and pull again.');
+  return state;
+}
+
+export function writeState(root, state) {
+  writeFile(root, '.autoappy/state.json', json({ ...state, format: STATE_FORMAT, version: STATE_VERSION }));
+}
+
+export function normalizeViewProject(value) {
+  const project = typeof value === 'string' ? JSON.parse(value) : value;
+  if (!project || project.format !== VIEW_FORMAT || project.version !== VIEW_VERSION || typeof project.entry !== 'string' || !Array.isArray(project.files)) {
+    throw new Error('Auto Appy returned an invalid frontend project.');
+  }
+  if (project.files.length > MAX_FILES) throw new Error(`Keep the frontend within ${MAX_FILES} files.`);
+  const seen = new Set();
+  let bytes = 0;
+  const files = project.files.map(file => {
+    if (!file || typeof file.path !== 'string' || typeof file.content !== 'string') throw new Error('Frontend files must contain path and content strings.');
+    assertSafeRelative(file.path);
+    if (!ALLOWED_APP_EXTENSIONS.has(path.extname(file.path).toLowerCase())) throw new Error(`Unsupported hosted file: ${file.path}`);
+    if (seen.has(file.path.toLowerCase())) throw new Error(`Duplicate frontend file: ${file.path}`);
+    seen.add(file.path.toLowerCase());
+    bytes += Buffer.byteLength(file.content);
+    return { path: file.path, content: file.content };
+  }).sort((a, b) => a.path.localeCompare(b.path));
+  if (bytes > MAX_SOURCE_BYTES) throw new Error('Keep the frontend source within 4 MB.');
+  if (!files.some(file => file.path === project.entry)) throw new Error('The frontend entry file is missing.');
+  return { format: VIEW_FORMAT, version: VIEW_VERSION, entry: project.entry, files };
+}
+
+export function readLocalProject(root) {
+  const appRoot = projectFile(root, 'app');
+  if (!fs.existsSync(appRoot) || !fs.lstatSync(appRoot).isDirectory()) throw new Error('Missing app/ directory. Run autoappy init.');
+  const files = [];
+  function walk(directory, prefix = '') {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name.startsWith('.')) continue;
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const filename = path.join(directory, entry.name);
+      const stat = fs.lstatSync(filename);
+      if (stat.isSymbolicLink()) throw new Error(`Links are not supported in app/: ${relative}`);
+      if (stat.isDirectory()) walk(filename, relative);
+      else if (stat.isFile()) files.push({ path: relative, content: fs.readFileSync(filename, 'utf8') });
+      else throw new Error(`Special files are not supported in app/: ${relative}`);
+    }
+  }
+  walk(appRoot);
+  return normalizeViewProject({ format: VIEW_FORMAT, version: VIEW_VERSION, entry: 'index.html', files });
+}
+
+export function writeLocalProject(root, project) {
+  const normalized = normalizeViewProject(project);
+  const current = readLocalProject(root);
+  const nextNames = new Set(normalized.files.map(file => file.path));
+  for (const file of current.files) if (!nextNames.has(file.path)) removeFile(root, `app/${file.path}`);
+  for (const file of normalized.files) writeFile(root, `app/${file.path}`, file.content);
+}
+
+export function projectMap(project) {
+  return Object.fromEntries(normalizeViewProject(project).files.map(file => [file.path, file.content]));
+}

package/src/init.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const templateRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../templates/hosted-app');
+
+function copyTree(source, destination) {
+  if (fs.existsSync(destination)) {
+    const stat = fs.lstatSync(destination);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`Cannot initialize through a link or file: ${destination}`);
+  }
+  fs.mkdirSync(destination, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const from = path.join(source, entry.name);
+    const to = path.join(destination, entry.name);
+    if (fs.existsSync(to) && fs.lstatSync(to).isSymbolicLink()) throw new Error(`Cannot initialize through a link: ${to}`);
+    if (entry.isDirectory()) copyTree(from, to);
+    else if (entry.isFile()) {
+      if (fs.existsSync(to)) continue;
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+export function initialize(root) {
+  copyTree(templateRoot, root);
+  const example = path.join(root, '.env.example');
+  const env = path.join(root, '.env');
+  if (!fs.existsSync(env)) fs.copyFileSync(example, env);
+  return { root };
+}

package/src/sync.js

@@ -0,0 +1,134 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { hash, json, normalizeViewProject, projectMap, readJson, readLocalProject, readState, removeFile, writeFile, writeLocalProject, writeState } from './files.js';
+
+function mapProject(map, entry = 'index.html') {
+  return normalizeViewProject({ format: 'autoappy.view-project', version: 1, entry, files: Object.entries(map).map(([path, content]) => ({ path, content })) });
+}
+
+export function mergeProjects({ baseline, local, remote }) {
+  const old = baseline ? projectMap(baseline) : {};
+  const ours = projectMap(local);
+  const theirs = projectMap(remote);
+  const merged = {};
+  const conflicts = [];
+  for (const name of new Set([...Object.keys(old), ...Object.keys(ours), ...Object.keys(theirs)])) {
+    const before = old[name] ?? null;
+    const here = ours[name] ?? null;
+    const there = theirs[name] ?? null;
+    let value;
+    if (here === there) value = here;
+    else if (here === before) value = there;
+    else if (there === before) value = here;
+    else { conflicts.push({ path: name, baseline: before, local: here, remote: there }); continue; }
+    if (value !== null) merged[name] = value;
+  }
+  return { project: conflicts.length ? null : mapProject(merged, remote.entry), conflicts };
+}
+
+export async function pullCode({ root, client }) {
+  const remote = await client.source();
+  if (!remote?.project || !Number.isInteger(remote.version)) throw new Error('The backend does not yet provide the Auto Appy app-source synchronization contract.');
+  const project = normalizeViewProject(remote.project);
+  const state = readState(root);
+  const local = readLocalProject(root);
+  const result = mergeProjects({ baseline: state.code?.project, local, remote: project });
+  if (result.conflicts.length) {
+    writeFile(root, '.autoappy/conflicts.json', json({ format: 'autoappy.conflicts', version: 1, conflicts: result.conflicts }));
+    throw new Error(`${result.conflicts.length} frontend file conflict(s) found. Review .autoappy/conflicts.json; no app files were changed.`);
+  }
+  writeLocalProject(root, result.project);
+  state.code = { version: remote.version, sourceHash: remote.source_hash || hash(project), project };
+  writeState(root, state);
+  return { files: project.files.length, preserved: hash(result.project) !== hash(project) };
+}
+
+export async function pushCode({ root, client }) {
+  const local = readLocalProject(root);
+  const remote = await client.source();
+  if (!remote?.project || !Number.isInteger(remote.version)) throw new Error('The backend does not yet provide the Auto Appy app-source synchronization contract.');
+  const state = readState(root);
+  const remoteProject = normalizeViewProject(remote.project);
+  const baseline = state.code?.project;
+  if (!baseline && hash(local) !== hash(remoteProject)) throw new Error('Pull the app before its first push so Auto Appy can protect remote changes.');
+  if (baseline && hash(baseline) !== hash(remoteProject) && hash(local) !== hash(remoteProject)) throw new Error('The Auto Appy app changed remotely. Run pull and resolve conflicts before pushing.');
+  if (hash(local) === hash(remoteProject)) {
+    state.code = { version: remote.version, sourceHash: remote.source_hash || hash(remoteProject), project: remoteProject };
+    writeState(root, state);
+    return { changed: false, version: remote.version, files: local.files.length };
+  }
+  const saved = await client.saveSource({ expected_version: remote.version, source_hash: remote.source_hash || hash(remoteProject), request_id: crypto.randomUUID(), project: local });
+  if (!saved || !Number.isInteger(saved.version)) throw new Error('Auto Appy returned an incomplete deployment receipt. Check the app before retrying.');
+  state.code = { version: saved.version, sourceHash: saved.source_hash || hash(local), project: local, deploymentId: saved.deployment_id || null };
+  writeState(root, state);
+  return { changed: true, version: saved.version, files: local.files.length, live: saved.status === 'published' };
+}
+
+export async function pullDataDefinitions({ root, client, includeSchema = true, includeApis = true }) {
+  const kit = await client.devkit();
+  if (!kit?.database?.id || !Array.isArray(kit.apis)) throw new Error('Auto Appy returned an incomplete development kit.');
+  if (includeSchema && kit.schema) writeFile(root, `models/${kit.database.id}.json`, json(kit.schema));
+  const expectedApiFiles = new Set();
+  for (const api of includeApis ? kit.apis : []) {
+    const definition = { id: api.id, database_id: api.database_id, name: api.name, description: api.description || '', status: api.status, version: api.version, program: api.program || JSON.parse(api.source) };
+    const name = `apis/${api.id}.json`;
+    expectedApiFiles.add(name);
+    writeFile(root, name, json(definition));
+  }
+  const apiDirectory = path.join(root, 'apis');
+  if (includeApis && fs.existsSync(apiDirectory)) for (const name of fs.readdirSync(apiDirectory)) {
+    const relative = `apis/${name}`;
+    if (/^[a-f0-9-]{36}\.json$/i.test(name) && !expectedApiFiles.has(relative)) removeFile(root, relative);
+  }
+  const state = readState(root);
+  state.devkit = {
+    ...(state.devkit || {}), pulledAt: new Date().toISOString(),
+    ...(includeSchema ? { databaseVersion: kit.database.version, schemaHash: kit.schema ? hash(kit.schema) : null } : {}),
+    ...(includeApis ? { apiVersions: Object.fromEntries(kit.apis.map(api => [api.id, api.version])) } : {}),
+  };
+  writeState(root, state);
+  return { database: kit.database.id, apis: includeApis ? kit.apis.length : 0, schema: includeSchema && Boolean(kit.schema) };
+}
+
+async function confirmed(question, yes) {
+  if (yes) return true;
+  if (!process.stdin.isTTY) throw new Error('Database changes require an interactive confirmation. CI may use --yes after reviewing the commit.');
+  const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try { return /^(y|yes)$/i.test((await prompt.question(`${question} [y/N] `)).trim()); }
+  finally { prompt.close(); }
+}
+
+export async function pushSchema({ root, client, config, yes = false }) {
+  const filename = path.join(root, 'models', `${config.appId}.json`);
+  const schema = readJson(filename);
+  if (!schema) throw new Error(`Missing models/${config.appId}.json. Run db pull first.`);
+  const plan = await client.planSchema(schema);
+  if (!plan?.token || !plan.review_hash || !Array.isArray(plan.changes)) throw new Error('Auto Appy returned an invalid database plan.');
+  console.log(json({ changes: plan.changes, warnings: plan.warnings || [] }).trim());
+  if (!await confirmed(`Apply ${plan.changes.length} reviewed database change(s)?`, yes)) return { applied: false, changes: plan.changes.length };
+  const receipt = await client.applySchema(plan.token, plan.review_hash);
+  return { applied: true, changes: plan.changes.length, receipt };
+}
+
+export async function pushApis({ root, client, config }) {
+  const directory = path.join(root, 'apis');
+  if (!fs.existsSync(directory)) return { saved: 0 };
+  const files = fs.readdirSync(directory).filter(name => /^[A-Za-z0-9_-]{1,100}\.json$/.test(name)).sort();
+  let savedCount = 0;
+  for (const name of files) {
+    const relative = `apis/${name}`;
+    const api = readJson(path.join(directory, name));
+    if (!api?.name || !api?.program || !['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(api.program.method)) throw new Error(`Invalid API definition: ${relative}`);
+    const payload = { name: api.name, description: api.description || '', source: JSON.stringify(api.program), ...(api.id ? { expected_version: api.version } : { database_id: api.database_id || config.appId }) };
+    const saved = api.id ? await client.updateApi(api.id, payload) : await client.createApi(payload);
+    if (!saved?.id || !Number.isInteger(saved.version)) throw new Error(`Auto Appy returned an incomplete API receipt for ${relative}. Check before retrying.`);
+    const normalized = { ...api, ...saved, program: api.program };
+    const destination = `apis/${saved.id}.json`;
+    writeFile(root, destination, json(normalized));
+    if (relative !== destination) removeFile(root, relative);
+    savedCount++;
+  }
+  return { saved: savedCount };
+}

package/templates/hosted-app/.env.example

@@ -0,0 +1,2 @@
+AUTOAPPY_BASE_URL=https://api.autoappy.com
+AUTOAPPY_APP_TOKEN=

package/templates/hosted-app/.vscode/tasks.json

@@ -0,0 +1,9 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    { "label": "Auto Appy: Start", "type": "npm", "script": "dev", "isBackground": true, "problemMatcher": [] },
+    { "label": "Auto Appy: Status", "type": "npm", "script": "status", "problemMatcher": [] },
+    { "label": "Auto Appy: Pull", "type": "npm", "script": "pull", "problemMatcher": [] },
+    { "label": "Auto Appy: Push", "type": "npm", "script": "push", "problemMatcher": [] }
+  ]
+}

package/templates/hosted-app/README.md

@@ -0,0 +1,9 @@
+# Auto Appy application
+
+1. Set the workspace and app UUIDs in `autoappy.json`.
+2. Set `AUTOAPPY_BASE_URL` and `AUTOAPPY_APP_TOKEN` in `.env`.
+3. Run `npm install` and `npm run pull`.
+4. Develop with `npm run dev`.
+5. Review with `npm run status`, then publish with `npm run push`.
+
+Database commands synchronize schema definitions, not customer records.

package/templates/hosted-app/app/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auto Appy application</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/App.jsx"></script>
+  </body>
+</html>

package/templates/hosted-app/app/src/App.jsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import './styles.css';
+
+function App() {
+  return (
+    <main className="app-shell">
+      <p className="eyebrow">Auto Appy</p>
+      <h1>Your application is connected.</h1>
+      <p>Edit <code>app/src/App.jsx</code>, then run <code>npm run push</code>.</p>
+    </main>
+  );
+}
+
+createRoot(document.getElementById('root')).render(<App />);

package/templates/hosted-app/app/src/styles.css

@@ -0,0 +1,36 @@
+:root {
+  color: #102f45;
+  background: #f4f9fc;
+  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+
+body {
+  margin: 0;
+}
+
+.app-shell {
+  box-sizing: border-box;
+  max-width: 760px;
+  min-height: 100vh;
+  margin: 0 auto;
+  padding: 18vh 32px 48px;
+}
+
+.eyebrow {
+  color: #147db5;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+h1 {
+  margin: 0 0 16px;
+  font-size: clamp(2.25rem, 7vw, 4.75rem);
+  line-height: 0.96;
+}
+
+code {
+  border-radius: 6px;
+  background: #e4f0f7;
+  padding: 2px 6px;
+}

package/templates/hosted-app/autoappy.json

@@ -0,0 +1,7 @@
+{
+  "format": "autoappy.project",
+  "version": 1,
+  "workspaceId": "REPLACE_WITH_WORKSPACE_UUID",
+  "appId": "REPLACE_WITH_APP_UUID",
+  "sourceDirectory": "app"
+}

package/templates/hosted-app/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "autoappy-application",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "autoappy dev",
+    "check": "autoappy check",
+    "status": "autoappy status",
+    "pull": "autoappy pull",
+    "push": "autoappy push",
+    "code:pull": "autoappy code pull",
+    "code:push": "autoappy code push",
+    "db:pull": "autoappy db pull",
+    "db:push": "autoappy db push",
+    "api:pull": "autoappy api pull",
+    "api:push": "autoappy api push"
+  },
+  "dependencies": {
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
+  "devDependencies": {
+    "@autoappy/cli": "0.1.0-beta.0",
+    "vite": "6.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}