@descix/cli 1.0.6 → 1.0.8

package/templates/agent-claude.md

@@ -159,7 +159,7 @@ To see your app in a browser:
 | Goal | Command |
 |------|---------|
 | Serve `site/` locally | `npx serve site/` or `python3 -m http.server -d site/` on any port |
-| Register port with DeSciX | `descix site servelocal <port> -c <community> -a <app>` |
+| Register a framework dev-server port with DeSciX | `descix app set-site -a <app> --port <port>` (writes `env.products[].site.port`) |
 | Run your app on the DeSciX gateway | `cd <app dir> && descix serve` — one HTTPS origin, the shell opens ON your app (**standalone** = initial view, not a reduced mode — platform views stay reachable) |
 
 A plain static server is enough to look at your HTML. `descix serve` is what you
@@ -257,8 +257,6 @@ Every app has three parts:
 
 - `descix status` may report "No workspace found" even when `.descix/workspace.json`
   exists. This is a known bug — continue with explicit flags.
-- `descix status` may suggest `descix setup` — that command doesn't exist. Use
-  `descix init -c <community> -a <app> -p .` instead.
 
 ## Cloud Brain Alignment
 

package/templates/agent-cline.md

@@ -121,7 +121,7 @@ descix kb corpus status -c <community> -a <app>
 | Goal | Command |
 |------|---------|
 | Serve `site/` locally | `npx serve site/` or `python3 -m http.server -d site/` on any port |
-| Register port with DeSciX | `descix site servelocal <port> -c <community> -a <app>` |
+| Register a framework dev-server port with DeSciX | `descix app set-site -a <app> --port <port>` (writes `env.products[].site.port`) |
 | Run your app on the DeSciX gateway | `cd <app dir> && descix serve` — one HTTPS origin, the shell opens ON your app (**standalone** = initial view, not a reduced mode — platform views stay reachable) |
 
 A plain static server is enough to look at your HTML. `descix serve` is what you
@@ -171,7 +171,6 @@ gateway does not rewrite paths.
 ## Known CLI Quirks
 
 - `descix status` may show "No workspace found" even when config exists — use explicit flags
-- `descix status` may suggest `descix setup` — use `descix init` instead
 
 ## Cloud Brain Alignment
 

package/templates/agent-copilot.md

@@ -121,7 +121,7 @@ descix kb corpus status -c <community> -a <app>
 | Goal | Command |
 |------|---------|
 | Serve `site/` locally | `npx serve site/` or `python3 -m http.server -d site/` on any port |
-| Register port with DeSciX | `descix site servelocal <port> -c <community> -a <app>` |
+| Register a framework dev-server port with DeSciX | `descix app set-site -a <app> --port <port>` (writes `env.products[].site.port`) |
 | Run your app on the DeSciX gateway | `cd <app dir> && descix serve` — one HTTPS origin, the shell opens ON your app (**standalone** = initial view, not a reduced mode — platform views stay reachable) |
 
 A plain static server is enough to look at your HTML. `descix serve` is what you
@@ -171,7 +171,6 @@ gateway does not rewrite paths.
 ## Known CLI Quirks
 
 - `descix status` may show "No workspace found" even when config exists — use explicit flags
-- `descix status` may suggest `descix setup` — use `descix init` instead
 
 ## Cloud Brain Alignment
 

package/templates/agent-cursor.md

@@ -121,7 +121,7 @@ descix kb corpus status -c <community> -a <app>
 | Goal | Command |
 |------|---------|
 | Serve `site/` locally | `npx serve site/` or `python3 -m http.server -d site/` on any port |
-| Register port with DeSciX | `descix site servelocal <port> -c <community> -a <app>` |
+| Register a framework dev-server port with DeSciX | `descix app set-site -a <app> --port <port>` (writes `env.products[].site.port`) |
 | Run your app on the DeSciX gateway | `cd <app dir> && descix serve` — one HTTPS origin, the shell opens ON your app (**standalone** = initial view, not a reduced mode — platform views stay reachable) |
 
 A plain static server is enough to look at your HTML. `descix serve` is what you
@@ -171,7 +171,6 @@ gateway does not rewrite paths.
 ## Known CLI Quirks
 
 - `descix status` may show "No workspace found" even when config exists — use explicit flags
-- `descix status` may suggest `descix setup` — use `descix init` instead
 
 ## Cloud Brain Alignment
 

package/templates/scaffolds/microservice/SERVICE_README_sdk.md

@@ -112,7 +112,7 @@ descix tell-me-how --scope discovery "What AI training tools exist?"
 ### descix app init
 
 **Description:** Create (if needed) and initialize an app: platform record + default KB + local workspace registration and scaffold. Idempotent.
-**Use when:** Starting a new project or hydrating an existing app. This is the single canonical path — the old two-step `app create` then `app init` is deleted; `descix app create` now hard-fails naming this replacement.
+**Use when:** Starting a new project or hydrating an existing app. This is the one command that creates an app.
 **Options:**
 - `-a, --app <app_id>` (required): App ID. With `-c` this is the app NAME to create.
 - `-c, --community <id>`: Community ID — required to create an app that does not exist yet

package/templates/scaffolds/microservice/templates/SERVICE_README_TEMPLATE.md

@@ -13,8 +13,7 @@ Run this sequence ONCE to stand up a microservice that can call the mesh
 `/apifront` broker:
 
 ```bash
-descix app create   -c {community} -a {app}     # create the app (or hydrate an existing one)
-descix app init      -a {community}-{app}        # scaffold site/ kb/ microservice/
+descix app init      -c {community} -a {app}     # create the app (or hydrate an existing one) and scaffold it
 descix app set-port  -a {community}-{app} -p {port}   # assign the microservice's loopback port in workspace.json
 descix microservice register                     # register the service manifest with the Core gateway
 # then: cp dev-overrides.example.json dev-overrides.json  and fill in the developer credential
@@ -117,7 +116,7 @@ descix microservice register                     # register the service manifest
 **Example:**
 ```bash
 # Using the CLI
-descix service call {command_name} --param1 value
+descix mcp execute --tool {command_name} --params '{"param1": "value"}'
 
 # Or via tell_me_how
 tell_me_how("I want to {describe the workflow goal}")

package/agent-assets/rules/descix_mcp.template.mdc

@@ -1,243 +0,0 @@
----
-alwaysApply: true
----
-
-# DeSciX SDK Agent Instructions
-
-You have SDK agent assets available locally at `{{SDK_ASSETS_PATH}}/`.
-
-## Key Architecture Concepts
-
-### Configuration: workspace.json is the Config File
-
-- **`workspace.json`** at `.descix/workspace.json` is the configuration file
-- **Context auto-detection** - CLI commands detect community/app from current working directory
-
-### CLI = Git Mode ONLY
-
-- The CLI only supports **git-mode** operations (local processing with Git version control)
-- **Drive-mode** apps are managed via PWA only (server-side processing)
-- All content starts on Drive - developers pull it locally, then manage with Git
-
-### App Folder Structure (Convention-Based)
-
-```
-my-app/
-├── assets/          # App metadata (icon.png, app_description.md, system_instructions.md)
-├── kb/              # Knowledge base
-│   ├── staging/     # Files to push TO Drive
-│   ├── General/     # Text files pulled FROM Drive
-│   └── chunks/      # Generated JSON chunks (Git-tracked)
-├── site/            # CodeSite static files (optional)
-└── microservice/    # Backend service code (optional)
-```
-
-## Post-Setup Initialization
-
-**IMPORTANT**: Check `.descix/workspace.json` for `_needsAgentSetup: true`.
-
-When this flag is set, the user has just completed `descix mcp quickstart` and needs your help configuring their workspace:
-
-1. **Greet the user** and confirm MCP is working: "I can see your DeSciX setup is complete. Let me help you configure your workspace."
-2. **Show their entitlements** from the cached JSON below (communities and apps they own)
-3. **Ask**: "Which app would you like to configure first?" or "Would you like me to scan your folders and suggest mappings?"
-4. **For each app folder**:
-   - Analyze the folder structure using heuristics from `{{SDK_ASSETS_PATH}}/instructions/folder-analysis.md`
-   - Recommend a packaging type using the decision tree from `{{SDK_ASSETS_PATH}}/instructions/packaging-types.md`
-   - Register the app in `workspace.json` with its localPath and absolutePath
-5. **When done**, set `_needsAgentSetup: false` in workspace.json
-
-If user asks "Help me configure my workspace" or similar, follow this flow.
-
-## Entitlements-First Principle
-
-**CRITICAL**: Users purchase apps/communities in the PWA first. Your role is to help configure local folders for apps they already own.
-
-### On First Interaction
-
-1. Check `.descix/workspace.json` for existing configuration
-2. If `_needsAgentSetup: true`, follow the Post-Setup Initialization flow above
-3. If unconfigured, read `{{SDK_ASSETS_PATH}}/instructions/onboarding-flow.md`
-4. For fresh entitlements: `execute_remote_command({ command: "fetch_my_purchases" })`
-5. Guide user through folder-to-app mapping in `workspace.json`
-
-## Local Asset References
-
-For quick decisions, read these local files (no network required):
-
-| File | Purpose |
-|------|---------|
-| `{{SDK_ASSETS_PATH}}/instructions/packaging-types.md` | App type taxonomy and decision tree |
-| `{{SDK_ASSETS_PATH}}/instructions/folder-analysis.md` | Detect project type from files |
-| `{{SDK_ASSETS_PATH}}/instructions/conversation-guides.md` | Dialogue templates |
-| `{{SDK_ASSETS_PATH}}/instructions/onboarding-flow.md` | Full onboarding workflow |
-
-## Template Usage
-
-When scaffolding apps, use templates from `{{SDK_ASSETS_PATH}}/templates/`:
-
-| Packaging Type | Templates Available |
-|----------------|---------------------|
-| `knowledge-only` | Assets folder only |
-| `static-site` | Site folder scaffold |
-| `microservice` | `manifest.json.template`, `SERVICE_README.template` |
-| `dynamic-site` | Site + microservice scaffolds |
-
-Replace `{{PLACEHOLDER}}` values with actual data from user input.
-
-## User Entitlements (Cached at Setup)
-
-```json
-{{ENTITLEMENTS_JSON}}
-```
-
-**Primary Community**: {{PRIMARY_COMMUNITY}}
-
-Use this cached data for quick checks. For fresh data, call `fetch_my_purchases`.
-
-## Tiered Access Pattern
-
-Use the appropriate tier based on what you need:
-
-### Tier 1: Local Files (Instant)
-```javascript
-// Read instructions directly
-Read("{{SDK_ASSETS_PATH}}/instructions/packaging-types.md")
-```
-**Use for**: Quick lookups, decision trees, templates
-
-### Tier 2: tell_me_how (Semantic Discovery)
-```javascript
-tell_me_how({ 
-  question: "How do I scaffold a microservice?",
-  scope: "entitlements"
-})
-```
-**Use for**: Finding the right tool for a task
-
-### Tier 3: chat_with_kb (Rich Context)
-```javascript
-chat_with_kb({
-  communityId: "descix",
-  appId: "docs",
-  kbId: "sdk",
-  message: "Explain the deployment workflow for dynamic sites"
-})
-```
-**Use for**: Complex questions requiring reasoning
-
-### Tier 4: execute_remote_command (Action)
-```javascript
-execute_remote_command({
-  command: "scaffold_app_type",
-  params: { type: "microservice", app_id: "myapp", ... }
-})
-```
-**Use for**: Actually creating/modifying things
-
-## Tool Discovery
-
-Use `tell_me_how` to discover platform capabilities:
-
-```javascript
-// Discover tools for a task
-tell_me_how({ question: "How do I deploy my app?", scope: "entitlements" })
-
-// Then execute the recommended command
-execute_remote_command({ command: "discovered_command", params: {...} })
-```
-
-**Scope Options**:
-- `project`: Only tools for apps in workspace.json
-- `entitlements`: Tools for all apps user owns (default)
-- `discovery`: All platform tools (may show purchasable)
-
-## App Configuration Workflow
-
-When user wants to configure a folder:
-
-1. **Analyze folder** using heuristics from `folder-analysis.md`
-2. **Recommend packaging type** using decision tree from `packaging-types.md`
-3. **Present options** using dialogue from `conversation-guides.md`
-4. **Register app** in `workspace.json` with localPath and absolutePath
-5. **Guide CLI commands** based on packaging type
-
-## Primary CLI Commands
-
-Guide users to these git-mode commands:
-
-### Knowledge Base Commands
-| Command | Purpose |
-|---------|---------|
-| `descix drive pull` | Pull text-converted content from Drive |
-| `descix drive push` | Push staging files to Drive |
-| `descix kb corpus sync` | Generate JSON chunks from text files |
-| `descix kb corpus sync` | Push chunks to Pinecone |
-| `descix kb corpus sync` | Full pipeline: pull → chunk → sync |
-| `descix kb corpus status` | Show local vs Pinecone sync status |
-
-### Site Commands
-| Command | Purpose |
-|---------|---------|
-| `descix site init` | Copy site scaffold to app |
-| `descix site upload` | Deploy CodeSite to GCS |
-| `descix site servelocal [port]` | Register local dev server port |
-| `descix site list` | List deployed site files |
-| `descix site status` | Get deployment status |
-
-### Microservice Commands
-| Command | Purpose |
-|---------|---------|
-| `descix microservice init` | Copy microservice scaffold to app |
-| `descix microservice register` | Register microservice with gateway |
-| `descix microservice vectorize` | Vectorize README for discovery |
-| `descix microservice list` | List registered microservices |
-| `descix microservice health <name>` | Check microservice health |
-| `descix microservice reload` | Reload manifests (admin) |
-
-**Context Auto-Detection**: When run from within an app directory, these commands auto-detect community/app from `workspace.json`. Otherwise use `-c` and `-a` flags.
-
-## SDK Tools Available (Remote)
-
-These tools are auto-registered and discoverable via `tell_me_how`:
-
-| Tool | Purpose |
-|------|---------|
-| `scaffold_app_type` | Create boilerplate for chosen packaging type |
-| `analyze_folder_structure` | Detect project type from folder contents |
-| `get_app_sync_status` | Check what's synced (KB, site, service) |
-| `fetch_my_purchases` | Get user's entitlements |
-| `register_service` | Register microservice with gateway |
-| `vectorize_service_readme` | Enable tell_me_how discovery |
-
-## Key Principles
-
-1. **Never assume** - Always ask before creating mappings
-2. **Entitlements are truth** - Can't configure apps user doesn't own
-3. **Local first** - Read local assets before making network calls
-4. **Guide, don't dictate** - Present options, let user choose
-5. **workspace.json is truth** - All configuration goes here
-
-## Error Recovery
-
-If commands fail:
-1. Check authentication: Is `wallet.json` valid?
-2. Check entitlements: Does user own the app?
-3. Check configuration: Is app registered in `workspace.json`?
-4. Check location: Are you in the app directory or using `-c/-a` flags?
-5. Use `tell_me_how` to find alternative approaches
-
-### Common Errors
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| "Workspace not configured" | No workspace.json | Run `descix init` |
-| "Could not determine app context" | Not in app directory | `cd` to app or use `-c/-a` flags |
-| "ADC not configured" | Missing Google auth | Run `gcloud auth application-default login` |
-| "App not found in workspace" | App not registered | Run `descix mcp quickstart` or add to workspace.json |
-
----
-
-*Generated by DeSciX SDK Setup*
-*SDK Version: {{SDK_VERSION}}*
-*Workspace: {{WORKSPACE_PATH}}*

package/lib/commands/briefer/errors.js

@@ -1,88 +0,0 @@
-/**
- * BrieferExtractorError — canonical hard-fail surface for the `descix briefer` CLI.
- *
- * Per WS-DESCIX-BRIEFER-CLI scope doc §2.3 ("Hard-fail philosophy"), every data
- * source has exactly one extraction method and exactly one failure mode:
- * HARD-FAIL with an actionable error message.
- *
- * Per feedback_no-hardcoded-fallbacks: NO fallback values, NO best-effort prose,
- * NO try-catch-and-default. If a source moved or changed shape, the CLI exits
- * non-zero and the canonical briefer file remains untouched.
- *
- * Stable error codes (per scope doc §2.3) — grep-friendly for diagnostics:
- *   BRIEFER-SRC-NOT-FOUND   Source file missing / line range no longer matches
- *   BRIEFER-GCLOUD-AUTH     gcloud auth missing or insufficient scope
- *   BRIEFER-GCLOUD-FAIL     gcloud probe failed (auth/empty/timeout) when --env=demo|prod required it
- *   BRIEFER-PARSE-FAIL      Source file present but construct unparseable
- *   BRIEFER-DRIFT-DETECTED  --check diff against canonical briefer non-empty
- *   BRIEFER-NEGATIVE-CLAIM  Briefer claims X does not exist, but found at Y:Z
- *   BRIEFER-FIRESTORE       Firestore read via apifront failed
- *   BRIEFER-NOT-IMPLEMENTED M1 stub — extractor scaffold-only, real impl in later milestone
- *
- * Per scope doc §2.3, every error message must include:
- *   1. The exact source path + line range that was being read.
- *   2. The construct shape that was expected.
- *   3. What the operator should do to recover.
- *   4. A stable error code from the list above.
- */
-
-export const BRIEFER_ERROR_CODES = Object.freeze({
-  SRC_NOT_FOUND: 'BRIEFER-SRC-NOT-FOUND',
-  GCLOUD_AUTH: 'BRIEFER-GCLOUD-AUTH',
-  PARSE_FAIL: 'BRIEFER-PARSE-FAIL',
-  DRIFT_DETECTED: 'BRIEFER-DRIFT-DETECTED',
-  NEGATIVE_CLAIM: 'BRIEFER-NEGATIVE-CLAIM',
-  FIRESTORE: 'BRIEFER-FIRESTORE',
-  GCLOUD_FAIL: 'BRIEFER-GCLOUD-FAIL',
-  NOT_IMPLEMENTED: 'BRIEFER-NOT-IMPLEMENTED',
-  WORKSPACE_NOT_FOUND: 'BRIEFER-WORKSPACE-NOT-FOUND'
-});
-
-export class BrieferExtractorError extends Error {
-  /**
-   * @param {object} args
-   * @param {string} args.code       One of BRIEFER_ERROR_CODES (REQUIRED).
-   * @param {string} args.section    Briefer section being extracted (e.g., '§3 routing').
-   * @param {string} args.source     File path or 'gcloud' or 'firestore' (REQUIRED).
-   * @param {string} args.expected   Construct shape that was expected (REQUIRED).
-   * @param {string} args.recovery   Concrete next step for the operator (REQUIRED).
-   * @param {string} [args.detail]   Optional extra context (e.g., parser msg, exit code).
-   */
-  constructor({ code, section, source, expected, recovery, detail } = {}) {
-    if (!code || !Object.values(BRIEFER_ERROR_CODES).includes(code)) {
-      // Hard-fail loud on misuse — caller is constructing a bad error.
-      // We do NOT default the code; per feedback_no-hardcoded-fallbacks the
-      // absence of a code is itself a misconfiguration we want to surface.
-      throw new Error(
-        `BrieferExtractorError requires a valid 'code'. Got: ${JSON.stringify(code)}. ` +
-        `Valid codes: ${Object.values(BRIEFER_ERROR_CODES).join(', ')}.`
-      );
-    }
-    if (!source) {
-      throw new Error(`BrieferExtractorError requires a 'source' (file path / 'gcloud' / 'firestore').`);
-    }
-    if (!expected) {
-      throw new Error(`BrieferExtractorError requires an 'expected' construct shape description.`);
-    }
-    if (!recovery) {
-      throw new Error(`BrieferExtractorError requires a 'recovery' instruction for the operator.`);
-    }
-
-    const lines = [
-      `[${code}] ${section || '(section unspecified)'}`,
-      `  source:   ${source}`,
-      `  expected: ${expected}`,
-      `  recovery: ${recovery}`
-    ];
-    if (detail) lines.push(`  detail:   ${detail}`);
-
-    super(lines.join('\n'));
-    this.name = 'BrieferExtractorError';
-    this.code = code;
-    this.section = section || null;
-    this.source = source;
-    this.expected = expected;
-    this.recovery = recovery;
-    this.detail = detail || null;
-  }
-}