@compilr-dev/sdk 0.1.14 → 0.1.16

package/dist/meta-tools/registry.d.ts

@@ -27,7 +27,7 @@ export interface MetaToolStats {
 export interface MetaTools {
     /** Lists available tools by category */
     listToolsTool: Tool;
-    /** Returns the JSON schema for a tool's parameters */
+    /** Returns compact parameter info for a tool */
     getToolInfoTool: Tool;
     /** Executes any registered tool by name */
     useToolTool: Tool;
@@ -91,4 +91,4 @@ export declare class MetaToolsRegistry {
  * Create the three meta-tools + fallback handler, all bound to a registry instance.
  */
 export declare function createMetaTools(registry: MetaToolsRegistry): MetaTools;
-export declare const META_TOOLS_SYSTEM_PROMPT_PREFIX = "\n## Tool Index (Specialized Tools)\n\nThese tools are called **exactly like direct tools** \u2014 just use the tool name with parameters. No special syntax or wrapper needed. The system routes them automatically.\n\n**IMPORTANT \u2014 These are CLI system tools, NOT your project's backend. Never use localhost/curl to access them.**\n\n**Parameter Rules:**\n- For **zero-parameter calls**: call the tool directly (e.g., `workitem_query()`, `git_status()`).\n- For **calls WITH parameters**: you MUST call `get_tool_info(\"tool_name\")` first to get the exact JSON schema. The signatures below are summaries only \u2014 do NOT guess parameter structure from them.\n- After a failed tool call, always call `get_tool_info()` before retrying.\n\n";
+export declare const META_TOOLS_SYSTEM_PROMPT_PREFIX = "\n## Tool Index (Specialized Tools)\n\nThese tools are called **exactly like direct tools** \u2014 just use the tool name with parameters. No special syntax or wrapper needed. The system routes them automatically.\n\n**IMPORTANT \u2014 These are CLI system tools, NOT your project's backend. Never use localhost/curl to access them.**\n\n**Parameter Rules:**\n- For **zero-parameter calls**: call the tool directly (e.g., `workitem_query()`, `git_status()`).\n- For **calls WITH parameters**: you MUST call `get_tool_info(\"tool_name\")` first to get parameter details. The signatures below are summaries only \u2014 do NOT guess parameter structure from them.\n- After a failed tool call, always call `get_tool_info()` before retrying.\n\n";

package/dist/meta-tools/registry.js

@@ -187,7 +187,7 @@ export function createMetaTools(registry) {
     // -------------------------------------------------------------------------
     const getToolInfoTool = defineTool({
         name: 'get_tool_info',
-        description: "Get the exact JSON schema for a tool's parameters. " +
+        description: "Get a tool's parameter signature and descriptions. " +
             'MUST be called before passing any parameters to a Tool Index tool. ' +
             'Zero-parameter calls do not need this.',
         inputSchema: {
@@ -211,11 +211,7 @@ export function createMetaTools(registry) {
                     `Available tools include: ${availableTools.join(', ')}... ` +
                     `Check the Tool Index for the full list.`));
             }
-            return Promise.resolve(createSuccessResult({
-                name: tool.definition.name,
-                description: tool.definition.description,
-                parameters: tool.definition.inputSchema,
-            }));
+            return Promise.resolve(createSuccessResult(buildCompactSchema(tool)));
         },
     });
     // -------------------------------------------------------------------------
@@ -267,9 +263,8 @@ export function createMetaTools(registry) {
             // 2. Validate args
             const validationError = registry.validateArgs(tool_name, args);
             if (validationError) {
-                return createErrorResult(`Invalid arguments for '${tool_name}': ${validationError}. ` +
-                    `Expected schema: ${JSON.stringify(tool.definition.inputSchema, null, 2)}. ` +
-                    `Hint: Call get_tool_info("${tool_name}") to see full parameter details.`);
+                return createErrorResult(`Invalid arguments for '${tool_name}': ${validationError}.\n` +
+                    `Expected:\n${buildCompactSchema(tool)}`);
             }
             // 3. Execute the tool
             try {
@@ -347,7 +342,7 @@ These tools are called **exactly like direct tools** — just use the tool name
 
 **Parameter Rules:**
 - For **zero-parameter calls**: call the tool directly (e.g., \`workitem_query()\`, \`git_status()\`).
-- For **calls WITH parameters**: you MUST call \`get_tool_info("tool_name")\` first to get the exact JSON schema. The signatures below are summaries only — do NOT guess parameter structure from them.
+- For **calls WITH parameters**: you MUST call \`get_tool_info("tool_name")\` first to get parameter details. The signatures below are summaries only — do NOT guess parameter structure from them.
 - After a failed tool call, always call \`get_tool_info()\` before retrying.
 
 `;
@@ -372,6 +367,22 @@ function getCategoryName(prefix) {
     };
     return categoryMap[prefix] ?? 'Other';
 }
+/**
+ * Resolve a compact type string from a JSON Schema property.
+ */
+function resolveCompactType(prop) {
+    const type = typeof prop.type === 'string' ? prop.type : 'any';
+    if (type === 'array') {
+        const items = prop.items;
+        const itemType = typeof items?.type === 'string' ? items.type : 'any';
+        return `${itemType}[]`;
+    }
+    if (type === 'boolean')
+        return 'bool';
+    if (type === 'integer')
+        return 'int';
+    return type;
+}
 /**
  * Build a concise signature for a tool.
  * e.g., "git_commit(message: string, files?: string[]) - Create a commit"
@@ -383,7 +394,7 @@ function buildToolSignature(tool) {
         const required = new Set(schema.required ?? []);
         for (const [name, prop] of Object.entries(schema.properties)) {
             const isRequired = required.has(name);
-            const type = prop.type ?? 'any';
+            const type = resolveCompactType(prop);
             params.push(isRequired ? `${name}: ${type}` : `${name}?: ${type}`);
         }
     }
@@ -391,6 +402,51 @@ function buildToolSignature(tool) {
     const desc = tool.definition.description.split('.')[0]; // First sentence
     return `${tool.definition.name}(${paramsStr}) - ${desc}`;
 }
+/**
+ * Build a compact schema string for get_tool_info responses.
+ * Includes signature, full description, and per-parameter details.
+ *
+ * Example output:
+ *   git_commit(message: string, files?: string[], amend?: bool)
+ *     Create a git commit with the specified message.
+ *     - message: The commit message (required)
+ *     - files: Files to stage before committing
+ *     - amend: Amend the last commit instead of creating new
+ */
+function buildCompactSchema(tool) {
+    const schema = tool.definition.inputSchema;
+    const required = new Set(schema.required ?? []);
+    const params = [];
+    const paramDetails = [];
+    if (schema.properties) {
+        for (const [name, prop] of Object.entries(schema.properties)) {
+            const isRequired = required.has(name);
+            const type = resolveCompactType(prop);
+            params.push(isRequired ? `${name}: ${type}` : `${name}?: ${type}`);
+            // Build parameter detail line
+            const desc = prop.description;
+            const enumValues = prop.enum;
+            let detail = `- ${name}`;
+            if (desc) {
+                detail += `: ${desc}`;
+            }
+            if (enumValues) {
+                detail += ` (${enumValues.map((v) => `"${v}"`).join('|')})`;
+            }
+            if (isRequired) {
+                detail += ' (required)';
+            }
+            paramDetails.push(detail);
+        }
+    }
+    const paramsStr = params.join(', ');
+    const lines = [`${tool.definition.name}(${paramsStr})`];
+    lines.push(`  ${tool.definition.description}`);
+    for (const detail of paramDetails) {
+        lines.push(`  ${detail}`);
+    }
+    return lines.join('\n');
+}
 /**
  * Format AJV validation errors into a readable string.
  */

package/dist/skills/platform-skills.js

@@ -69,7 +69,10 @@ When you have enough information:
    - Fill in: Problem Statement, Goals, User Stories, Functional Requirements
    - Keep the existing structure, just replace placeholder text
 5. Present the backlog and PRD summary to user for confirmation
-   - If CHORE-001 was added, mention: "Run /build to start with project scaffolding"
+   - If CHORE-001 was added, mention: "Run /scaffold to create the project foundation"
+6. If the project involves managing entities (CRUD operations on things like users, orders, products):
+   - Mention: "This looks like an entity-based app — /scaffold can auto-generate a full working MVP with CRUD pages, API, routing, and seed data."
+   - Do NOT build the Application Model during /design — /scaffold handles that
 
 ## RULES
 - Ask questions in batches of 2-4 using ask_user tool when possible
@@ -85,6 +88,7 @@ When you have enough information:
 ✓ Backlog has 5-15 items
 ✓ For fresh projects: CHORE-001 scaffolding item is first (critical priority)
 ✓ PRD.md is populated with requirements
+✓ If entity-based: user informed about /scaffold auto-generation
 ✓ User has approved the backlog`,
     tags: ['planning', 'requirements'],
 });
@@ -711,6 +715,26 @@ export const scaffoldSkill = defineSkill({
 - Need requirements first → use design skill
 - Modifying existing project → use appropriate skill
 
+## FACTORY CHECK (TRY THIS FIRST)
+
+Before manual scaffolding, check if the factory can auto-generate the project:
+
+1. Call \`app_model_get\` with \`{ "scope": "summary" }\` to check for an existing Application Model.
+   - If model exists with entities → use factory path: preview with \`factory_scaffold({ "dry_run": true })\`, confirm with user, then generate with \`factory_scaffold({ "output_dir": "{{projectPath}}" })\`.
+   - Skip the manual scaffold below entirely.
+
+2. If NO model exists, check project documents for entity patterns:
+   - Read PRD with \`project_document_get({ "doc_type": "prd" })\`
+   - If PRD mentions managing/tracking things (entities, CRUD, data types) → ask user:
+     "Your project involves managing [entities]. I can auto-generate a working app. Want me to use the factory? (Yes = build model + generate / No = manual scaffold)"
+   - If Yes → call \`factory_list_toolkits\` to show options, then build the model with \`app_model_update\` operations (set identity, techStack, add entities with fields, add relationships, set features/theme/layout), validate with \`app_model_validate\`, generate with \`factory_scaffold({ "output_dir": "{{projectPath}}" })\`.
+
+3. If no entities detected or user declines factory → proceed with MANUAL SCAFFOLD below.
+
+---
+
+## MANUAL SCAFFOLD (if factory not applicable)
+
 ## CRITICAL: PROJECT DIRECTORY
 
 **All files MUST be created in: {{projectPath}}**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",