@autoappy/cli 0.2.0-beta.0 → 0.3.0-beta.0

package/README.md

@@ -35,6 +35,7 @@ autoappy push
 autoappy code pull|push
 autoappy db pull|push
 autoappy api pull|push
+autoappy seed push
 autoappy check
 ```
 
@@ -42,6 +43,18 @@ autoappy check
 
 Database synchronization covers schema only. Customer records are never copied into the project or Git by these commands.
 
+## Seed a blank app once
+
+`autoappy.seed.json` is the complete initial project manifest. It can declare table schemas, fictional or starter records, managed APIs, View grants, and the main View. A View with `"source_directory": "app"` uses the real frontend files instead of embedding them in JSON.
+
+```bash
+npm run seed:push
+```
+
+The CLI sends one plan request, prints the full resource counts and warnings, asks for one confirmation, and applies one atomic backend transaction. The reviewed token is carried internally. The target must be a blank app. Repeating the same apply receipt is idempotent; a different seed never overwrites an initialized app. Afterward, use `db:push`, `api:push`, and `code:push` for ongoing changes.
+
+The seed file is for intentional initial fixtures, not a dump of production/customer rows. Normal pull never writes remote records into Git.
+
 ## Backend contract
 
 The Auto Appy development-kit, schema, managed-API, and versioned frontend endpoints are used directly:
@@ -49,6 +62,8 @@ The Auto Appy development-kit, schema, managed-API, and versioned frontend endpo
 ```text
 GET   /api/v1/platform/organisations/{workspace}/data/apps/{app}/source
 PATCH /api/v1/platform/organisations/{workspace}/data/apps/{app}/source
+POST  /api/v1/platform/organisations/{workspace}/data/apps/{app}/seed/plan
+POST  /api/v1/platform/organisations/{workspace}/data/apps/{app}/seed/{token}/apply
 ```
 
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autoappy/cli",
-  "version": "0.2.0-beta.0",
+  "version": "0.3.0-beta.0",
   "description": "Develop and synchronize Auto Appy applications from VS Code.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -4,6 +4,7 @@ import { AutoAppyClient } from './client.js';
 import { connectionEnvironment } from './env.js';
 import { hash, readConfig, readLocalProject, readState } from './files.js';
 import { initialize } from './init.js';
+import { pushSeed } from './seed.js';
 import { pullCode, pullDataDefinitions, pushApis, pushCode, pushSchema } from './sync.js';
 
 function help() {
@@ -22,6 +23,7 @@ Usage: autoappy <command>
   db push    Review and apply database schema changes
   api pull   Pull managed API definitions
   api push   Push managed API definitions
+  seed push  Seed a blank app from one reviewed JSON manifest
   check      Validate hosted frontend files
 `);
 }
@@ -88,6 +90,14 @@ export async function run(args, options = {}) {
     return;
   }
   if (command === 'api' && subcommand === 'push') return console.log(`Saved ${(await pushApis({ root, client, config })).saved} API definition(s).`);
+  if (command === 'seed' && subcommand === 'push') {
+    const result = await pushSeed({ root, client, yes });
+    if (!result.applied) return console.log('Initial seed was not applied.');
+    const code = await pullCode({ root, client });
+    const definitions = await pullDataDefinitions({ root, client });
+    console.log(`Seed complete: ${result.receipt.tables.length} table(s), ${result.receipt.record_count} record(s), ${result.receipt.apis.length} API(s), ${result.receipt.views.length} View(s); synchronized ${code.files} frontend file(s) and ${definitions.apis} API definition(s).`);
+    return;
+  }
   if (command === 'pull') {
     const code = await pullCode({ root, client });
     const definitions = await pullDataDefinitions({ root, client });

package/src/client.js

@@ -38,6 +38,8 @@ export class AutoAppyClient {
   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 }); }
+  planSeed(seed) { return this.request('POST', `apps/${encodeURIComponent(this.appId)}/seed/plan`, { seed }); }
+  applySeed(token, reviewHash) { return this.request('POST', `apps/${encodeURIComponent(this.appId)}/seed/${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/seed.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { json, readJson, readLocalProject, readState, writeLocalProject, writeState } from './files.js';
+import { confirmed } from './sync.js';
+
+export function readSeed(root) {
+  const filename = path.join(root, 'autoappy.seed.json');
+  const seed = readJson(filename);
+  if (!seed || seed.format !== 'autoappy.app-seed' || seed.version !== 1 || !Array.isArray(seed.tables) || !Array.isArray(seed.apis) || !Array.isArray(seed.views)) {
+    throw new Error('Create a valid autoappy.seed.json before running seed push.');
+  }
+  if (fs.statSync(filename).size > 8_000_000) throw new Error('Keep autoappy.seed.json within 8 MB.');
+  const views = seed.views.map(view => {
+    if (!view || typeof view !== 'object' || Array.isArray(view)) throw new Error('Every seed View must be a JSON object.');
+    if (view.source_directory !== undefined) {
+      if (view.source_directory !== 'app' || view.source !== undefined) throw new Error('A seed View may use source_directory: "app" or source, not both.');
+      const { source_directory, ...definition } = view;
+      return { ...definition, source: JSON.stringify(readLocalProject(root)) };
+    }
+    if (typeof view.source !== 'string') throw new Error('Every seed View needs source_directory: "app" or a source string.');
+    return view;
+  });
+  return { ...seed, views };
+}
+
+function resolveApiPlaceholders(project, apis) {
+  const ids = Object.fromEntries((apis || []).map(api => [api.key, api.id]));
+  return { ...project, files: project.files.map(file => ({ ...file, content: file.content.replace(/\{\{api:([a-z][a-z0-9_]{0,40})\}\}/g, (match, key) => ids[key] || match) })) };
+}
+
+export async function pushSeed({ root, client, yes = false }) {
+  const seed = readSeed(root);
+  const plan = await client.planSeed(seed);
+  if (!plan?.token || !plan.review_hash || !Array.isArray(plan.tables)) throw new Error('Auto Appy returned an invalid app seed review.');
+  console.log(json({ tables: plan.tables, records: plan.record_count, apis: plan.api_count, views: plan.view_count, main_view: plan.main_view, warnings: plan.warnings || [] }).trim());
+  if (!await confirmed(`Apply this initial seed with ${plan.record_count} record(s)?`, yes)) return { applied: false, plan };
+  const receipt = await client.applySeed(plan.token, plan.review_hash);
+  if (!receipt?.database_id || !Array.isArray(receipt.tables) || !Array.isArray(receipt.apis) || !Array.isArray(receipt.views)) {
+    throw new Error('Auto Appy returned an incomplete seed receipt. Check the app before retrying.');
+  }
+  const local = readLocalProject(root);
+  const resolved = resolveApiPlaceholders(local, receipt.apis);
+  writeLocalProject(root, resolved);
+  const state = readState(root);
+  state.seed = { appliedAt: new Date().toISOString(), reviewHash: plan.review_hash, receipt };
+  writeState(root, state);
+  return { applied: true, plan, receipt };
+}

package/src/sync.js

@@ -111,7 +111,7 @@ export async function pullDataDefinitions({ root, client, includeSchema = true,
   return { database: kit.database.id, apis: includeApis ? kit.apis.length : 0, schema: includeSchema && Boolean(kit.schema) };
 }
 
-async function confirmed(question, yes) {
+export 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 });

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

@@ -3,6 +3,7 @@
   "tasks": [
     { "label": "Auto Appy: Start", "type": "npm", "script": "dev", "isBackground": true, "problemMatcher": [] },
     { "label": "Auto Appy: Status", "type": "npm", "script": "status", "problemMatcher": [] },
+    { "label": "Auto Appy: Seed blank app", "type": "npm", "script": "seed:push", "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

@@ -8,3 +8,5 @@
 
 Database commands synchronize schema definitions, not customer records.
 The first pull keeps this starter when the Auto Appy app has no frontend yet. The first push creates and publishes it.
+
+For a completely blank app, edit `autoappy.seed.json` to declare initial table schemas, starter rows, managed APIs, View connections, and the main View. Keep `source_directory: "app"` to use the real files in `app/`, then run `npm run seed:push`. It reviews and commits the whole initial project atomically. Use normal pull/push commands after the seed succeeds.

package/templates/hosted-app/autoappy.seed.json

@@ -0,0 +1,17 @@
+{
+  "format": "autoappy.app-seed",
+  "version": 1,
+  "main_view": "app",
+  "tables": [],
+  "apis": [],
+  "views": [
+    {
+      "key": "app",
+      "name": "Application frontend",
+      "source_directory": "app",
+      "tables": [],
+      "apis": [],
+      "allow_writes": false
+    }
+  ]
+}

package/templates/hosted-app/package.json

@@ -14,14 +14,15 @@
     "db:pull": "autoappy db pull",
     "db:push": "autoappy db push",
     "api:pull": "autoappy api pull",
-    "api:push": "autoappy api push"
+    "api:push": "autoappy api push",
+    "seed:push": "autoappy seed push"
   },
   "dependencies": {
     "react": "18.3.1",
     "react-dom": "18.3.1"
   },
   "devDependencies": {
-    "@autoappy/cli": "0.2.0-beta.0",
+    "@autoappy/cli": "0.3.0-beta.0",
     "vite": "6.1.0"
   },
   "engines": {