@carthooks/arcubase-cli 0.1.2 → 0.1.3

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

@@ -0,0 +1,123 @@
+# 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.
+
+## 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
+
+## 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/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)
+}