@carthooks/arcubase-cli 0.1.2 → 0.1.4

package/sdk-dist/docs/runtime-reference/table-lifecycle.md

@@ -0,0 +1,135 @@
+# Table Lifecycle
+
+Use this page when the goal is:
+
+- create an app
+- create a table
+- save the schema
+- confirm the table is really ready
+
+The successful path is command-first:
+
+1. create the app
+2. create the entity shell
+3. fetch the current shell
+4. save the full schema
+5. probe rows with `query-entity`
+
+Do not stop at shell creation.
+
+CLI phase split:
+
+- schema phase uses `arcubase-admin`
+- row phase uses `arcubase`
+- the switch happens immediately after `admin-save-entity`
+- do not use `arcubase-admin` for row insert or row query
+
+## Step 1: create the app
+
+Command:
+
+```bash
+arcubase-admin app create-app-by-tenants --body-file create-app.json
+```
+
+Minimal `create-app.json`:
+
+```json
+{
+  "name": "bt053"
+}
+```
+
+Rules:
+
+- `name` is required
+- keep `name` at `20` characters or fewer
+
+## Step 2: create the entity shell
+
+Command:
+
+```bash
+arcubase-admin app create-entity \
+  --id <app_id> \
+  --body-file create-entity.json
+```
+
+Minimal `create-entity.json`:
+
+```json
+{
+  "name": "simple"
+}
+```
+
+Rules:
+
+- this only creates the shell
+- this does not mean row CRUD is ready
+
+## Step 3: fetch the current shell
+
+Command:
+
+```bash
+arcubase-admin entity admin-get-entity-info \
+  --app-id <app_id> \
+  --entity-id <entity_id>
+```
+
+Use the returned shell as the base for `save-entity.json`.
+
+Rules:
+
+- do not invent `schema_version`
+- do not invent top-level `options`
+- keep `id`, `app_id`, `name`, and `workflow_enabled` from the shell
+- normalize shell placeholder `null` values before save
+
+## Step 4: save the full schema
+
+Command:
+
+```bash
+arcubase-admin entity admin-save-entity \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file save-entity.json
+```
+
+Read before writing `save-entity.json`:
+
+1. `entity-schema.md`
+2. `entity-schema/README.md`
+3. the exact field-type pages you need
+
+After `admin-save-entity`, switch binaries:
+
+- use `arcubase workflow insert-entity` for row insertion
+- use `arcubase workflow query-entity` for readiness and row reads
+
+## Step 5: probe readiness
+
+Command:
+
+```bash
+arcubase workflow query-entity \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file query.json
+```
+
+Minimal `query.json`:
+
+```json
+{
+  "limit": 20,
+  "offset": 0
+}
+```
+
+Rules:
+
+- only call the table ready after this command succeeds
+- if shell creation succeeded but `query-entity` still fails, the table is not ready

package/sdk-dist/docs/runtime-reference/uploads.md

@@ -0,0 +1,106 @@
+# Uploads
+
+Use this page when a row contains a `file` or `image` field.
+
+The successful path is:
+
+1. run `arcubase upload <local-file>`
+2. use the returned JSON array directly as the field value
+3. insert or update the row with `arcubase workflow insert-entity` or `arcubase workflow update-entity-row`
+
+Do not construct `upload_id`, `assets_id`, or OSS form fields by hand.
+
+## Upload one local file
+
+Command:
+
+```bash
+arcubase upload ./contract.pdf
+```
+
+Optional flags:
+
+- `--filename <name>`
+- `--global`
+
+Example:
+
+```bash
+arcubase upload ./lead-photo.jpg --filename lead-photo.jpg
+```
+
+## Upload result shape
+
+The command returns a JSON array.
+
+Example:
+
+```json
+{
+  "data": [
+    {
+      "upload_id": 123456,
+      "file": "contract.pdf",
+      "file_name": "contract.pdf",
+      "meta": {}
+    }
+  ]
+}
+```
+
+Use the `data` array directly as the field value for a `file` or `image` field.
+
+## Insert a row with a file field
+
+```json
+{
+  "fields": {
+    "1001": "Lead A",
+    "1007": [
+      {
+        "upload_id": 123456,
+        "file": "contract.pdf",
+        "file_name": "contract.pdf",
+        "meta": {}
+      }
+    ]
+  }
+}
+```
+
+## Update a row with an image field
+
+```json
+{
+  "data": {
+    "1008": [
+      {
+        "upload_id": 123457,
+        "file": "lead-photo.jpg",
+        "file_name": "lead-photo.jpg",
+        "meta": {}
+      }
+    ]
+  },
+  "changed_fields": [1008]
+}
+```
+
+## Preview an uploaded file
+
+Command:
+
+```bash
+arcubase common upload-preview --body-file preview.json
+```
+
+Example `preview.json`:
+
+```json
+{
+  "upload_id": 123456,
+  "fname": "contract.pdf"
+}
+```
+
+This returns a preview URL for the upload token entry. It does not insert or update a row.

package/sdk-dist/docs/runtime-reference/workflow/README.md

@@ -0,0 +1,19 @@
+# Workflow Runtime Reference
+
+This directory is reserved for future workflow runtime docs.
+
+It will follow the same single-path distribution model as entity schema docs:
+
+- Development source of truth:
+  - `misc/packages/@carthooks/arcubase-cli/docs/runtime-reference/workflow/`
+- Runtime location:
+  - `/opt/arcubase-sdk/docs/runtime-reference/workflow/`
+- Distribution path:
+  - `sdk-dist/docs/runtime-reference/workflow/`
+
+Expected coverage later:
+
+- workflow configuration lifecycle
+- real writable structure for nodes, edges, actions, and conditions
+- integration points between workflow and entity schema
+- common failure cases and debugging guidance

package/src/runtime/command_registry.ts

@@ -20,3 +20,50 @@ export function listModules(scope: CommandScope): string[] {
 export function listModuleCommands(scope: CommandScope, moduleName: string): readonly CommandDef[] {
   return listCommands(scope).filter((item) => item.commandPath[0] === moduleName)
 }
+
+function levenshtein(a: string, b: string): number {
+  const dp = Array.from({ length: a.length + 1 }, () => new Array<number>(b.length + 1).fill(0))
+  for (let i = 0; i <= a.length; i += 1) dp[i][0] = i
+  for (let j = 0; j <= b.length; j += 1) dp[0][j] = j
+  for (let i = 1; i <= a.length; i += 1) {
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost,
+      )
+    }
+  }
+  return dp[a.length][b.length]
+}
+
+export type CommandSuggestion = {
+  scope: CommandScope
+  moduleName: string
+  commandName: string
+  binary: 'arcubase-admin' | 'arcubase'
+  score: number
+}
+
+export function findCommandSuggestions(moduleName: string, commandName: string, limit = 3): CommandSuggestion[] {
+  const suggestions: CommandSuggestion[] = []
+  for (const scope of ['admin', 'user'] as const) {
+    for (const command of listCommands(scope)) {
+      const [candidateModule, candidateCommand] = command.commandPath
+      const moduleScore = candidateModule === moduleName ? 0 : levenshtein(candidateModule, moduleName || '')
+      const commandScore = candidateCommand === commandName ? 0 : levenshtein(candidateCommand, commandName || '')
+      const score = commandScore * 3 + moduleScore
+      suggestions.push({
+        scope,
+        moduleName: candidateModule,
+        commandName: candidateCommand,
+        binary: scope === 'admin' ? 'arcubase-admin' : 'arcubase',
+        score,
+      })
+    }
+  }
+  return suggestions
+    .sort((a, b) => a.score - b.score || a.binary.localeCompare(b.binary) || a.moduleName.localeCompare(b.moduleName) || a.commandName.localeCompare(b.commandName))
+    .slice(0, limit)
+}