@databricks/appkit-ui 0.23.0 → 0.24.0

package/CLAUDE.md

@@ -52,6 +52,7 @@ npx @databricks/appkit docs <query>
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
 - [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.
 - [Serving plugin](./docs/plugins/serving.md): Provides an authenticated proxy to Databricks Model Serving endpoints, with invoke and streaming support.
+- [Vector Search plugin](./docs/plugins/vector-search.md): Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
 
 ## appkit API reference [collapsed]
 

package/dist/cli/commands/docs.js

@@ -103,7 +103,13 @@ function runDocs(query, options) {
 	const output = header + sections.map((s) => s.collapsed ? formatCollapsedSection(s) : formatExpandedSection(s)).join("\n");
 	console.log(output);
 }
-const docsCommand = new Command("docs").description("Display embedded documentation").argument("[query]", "Section name (e.g. 'plugins') or path to a doc file (e.g. './docs.md')").option("--full", "Show complete index including all API reference entries").action(runDocs);
+const docsCommand = new Command("docs").description("Display embedded documentation").argument("[query]", "Section name (e.g. 'plugins') or path to a doc file (e.g. './docs.md')").option("--full", "Show complete index including all API reference entries").addHelpText("after", `
+Examples:
+  $ appkit docs
+  $ appkit docs plugins
+  $ appkit docs "appkit-ui API reference"
+  $ appkit docs ./docs/plugins/analytics.md
+  $ appkit docs --full`).action(runDocs);
 
 //#endregion
 export { docsCommand };

package/dist/cli/commands/docs.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs.js","names":[],"sources":["../../../src/cli/commands/docs.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { Command } from \"commander\";\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nconst COLLAPSED_MARKER = \"[collapsed]\";\n\ninterface Section {\n  name: string;\n  body: string;\n  collapsed: boolean;\n}\n\nfunction findPackageRoot(): string {\n  let dir = __dirname;\n  while (dir !== path.parse(dir).root) {\n    if (fs.existsSync(path.join(dir, \"package.json\"))) {\n      return dir;\n    }\n    dir = path.dirname(dir);\n  }\n  throw new Error(\"Could not find package root\");\n}\n\nfunction parseSections(content: string): {\n  header: string;\n  sections: Section[];\n} {\n  const parts = content.split(/^(## .+)$/m);\n  const header = parts[0];\n  const sections: Section[] = [];\n\n  for (let i = 1; i < parts.length; i += 2) {\n    const rawName = parts[i].replace(/^## /, \"\");\n    const body = parts[i + 1] ?? \"\";\n    const collapsed = rawName.includes(COLLAPSED_MARKER);\n    const name = rawName.replace(COLLAPSED_MARKER, \"\").trim();\n    sections.push({ name, body, collapsed });\n  }\n\n  return { header, sections };\n}\n\nfunction countPages(body: string): number {\n  return (body.match(/^- \\[/gm) || []).length;\n}\n\nfunction findSections(sections: Section[], query: string): Section[] {\n  const q = query.toLowerCase();\n  return sections.filter((s) => s.name.toLowerCase().includes(q));\n}\n\nfunction isFilePath(arg: string): boolean {\n  return arg.startsWith(\"./\") && arg.endsWith(\".md\");\n}\n\nfunction readLlmsTxt(packageRoot: string): string {\n  const llmsPath = path.join(packageRoot, \"llms.txt\");\n  if (!fs.existsSync(llmsPath)) {\n    console.error(\"Error: llms.txt not found in package\");\n    process.exit(1);\n  }\n  return fs.readFileSync(llmsPath, \"utf-8\");\n}\n\nfunction readDocFile(packageRoot: string, docPath: string): void {\n  let normalizedPath = docPath;\n  normalizedPath = normalizedPath.replace(/^\\.\\//, \"\");\n  normalizedPath = normalizedPath.replace(/^\\//, \"\");\n  normalizedPath = normalizedPath.replace(/^appkit\\//, \"\");\n\n  const fullPath = path.join(packageRoot, normalizedPath);\n\n  if (!fs.existsSync(fullPath)) {\n    console.error(`Error: Documentation file not found: ${docPath}`);\n    console.error(`Tried: ${fullPath}`);\n    process.exit(1);\n  }\n\n  console.log(fs.readFileSync(fullPath, \"utf-8\"));\n}\n\nfunction formatCollapsedSection(section: Section): string {\n  const pages = countPages(section.body);\n  return [\n    `## ${section.name} (${pages} pages)`,\n    \"\",\n    `> Use \\`appkit docs \"${section.name}\"\\` to expand, or \\`appkit docs --full\\` to expand all sections.`,\n    \"\",\n  ].join(\"\\n\");\n}\n\nfunction formatExpandedSection(section: Section): string {\n  return `## ${section.name}${section.body}`;\n}\n\nfunction runDocs(query: string | undefined, options: { full?: boolean }) {\n  const packageRoot = findPackageRoot();\n\n  if (query && isFilePath(query)) {\n    readDocFile(packageRoot, query);\n    return;\n  }\n\n  const content = readLlmsTxt(packageRoot);\n\n  if (options.full) {\n    console.log(content.replaceAll(` ${COLLAPSED_MARKER}`, \"\"));\n    return;\n  }\n\n  const { header, sections } = parseSections(content);\n\n  if (query) {\n    const matched = findSections(sections, query);\n    if (matched.length === 0) {\n      const available = sections.map((s) => `  - ${s.name}`).join(\"\\n\");\n      console.error(\n        `No section matching \"${query}\". Available sections:\\n${available}`,\n      );\n      process.exit(1);\n    }\n    console.log(matched.map(formatExpandedSection).join(\"\\n\"));\n    return;\n  }\n\n  const output =\n    header +\n    sections\n      .map((s) =>\n        s.collapsed ? formatCollapsedSection(s) : formatExpandedSection(s),\n      )\n      .join(\"\\n\");\n  console.log(output);\n}\n\nexport const docsCommand = new Command(\"docs\")\n  .description(\"Display embedded documentation\")\n  .argument(\n    \"[query]\",\n    \"Section name (e.g. 'plugins') or path to a doc file (e.g. './docs.md')\",\n  )\n  .option(\"--full\", \"Show complete index including all API reference entries\")\n  .action(runDocs);\n"],"mappings":"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"}
+{"version":3,"file":"docs.js","names":[],"sources":["../../../src/cli/commands/docs.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { Command } from \"commander\";\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nconst COLLAPSED_MARKER = \"[collapsed]\";\n\ninterface Section {\n  name: string;\n  body: string;\n  collapsed: boolean;\n}\n\nfunction findPackageRoot(): string {\n  let dir = __dirname;\n  while (dir !== path.parse(dir).root) {\n    if (fs.existsSync(path.join(dir, \"package.json\"))) {\n      return dir;\n    }\n    dir = path.dirname(dir);\n  }\n  throw new Error(\"Could not find package root\");\n}\n\nfunction parseSections(content: string): {\n  header: string;\n  sections: Section[];\n} {\n  const parts = content.split(/^(## .+)$/m);\n  const header = parts[0];\n  const sections: Section[] = [];\n\n  for (let i = 1; i < parts.length; i += 2) {\n    const rawName = parts[i].replace(/^## /, \"\");\n    const body = parts[i + 1] ?? \"\";\n    const collapsed = rawName.includes(COLLAPSED_MARKER);\n    const name = rawName.replace(COLLAPSED_MARKER, \"\").trim();\n    sections.push({ name, body, collapsed });\n  }\n\n  return { header, sections };\n}\n\nfunction countPages(body: string): number {\n  return (body.match(/^- \\[/gm) || []).length;\n}\n\nfunction findSections(sections: Section[], query: string): Section[] {\n  const q = query.toLowerCase();\n  return sections.filter((s) => s.name.toLowerCase().includes(q));\n}\n\nfunction isFilePath(arg: string): boolean {\n  return arg.startsWith(\"./\") && arg.endsWith(\".md\");\n}\n\nfunction readLlmsTxt(packageRoot: string): string {\n  const llmsPath = path.join(packageRoot, \"llms.txt\");\n  if (!fs.existsSync(llmsPath)) {\n    console.error(\"Error: llms.txt not found in package\");\n    process.exit(1);\n  }\n  return fs.readFileSync(llmsPath, \"utf-8\");\n}\n\nfunction readDocFile(packageRoot: string, docPath: string): void {\n  let normalizedPath = docPath;\n  normalizedPath = normalizedPath.replace(/^\\.\\//, \"\");\n  normalizedPath = normalizedPath.replace(/^\\//, \"\");\n  normalizedPath = normalizedPath.replace(/^appkit\\//, \"\");\n\n  const fullPath = path.join(packageRoot, normalizedPath);\n\n  if (!fs.existsSync(fullPath)) {\n    console.error(`Error: Documentation file not found: ${docPath}`);\n    console.error(`Tried: ${fullPath}`);\n    process.exit(1);\n  }\n\n  console.log(fs.readFileSync(fullPath, \"utf-8\"));\n}\n\nfunction formatCollapsedSection(section: Section): string {\n  const pages = countPages(section.body);\n  return [\n    `## ${section.name} (${pages} pages)`,\n    \"\",\n    `> Use \\`appkit docs \"${section.name}\"\\` to expand, or \\`appkit docs --full\\` to expand all sections.`,\n    \"\",\n  ].join(\"\\n\");\n}\n\nfunction formatExpandedSection(section: Section): string {\n  return `## ${section.name}${section.body}`;\n}\n\nfunction runDocs(query: string | undefined, options: { full?: boolean }) {\n  const packageRoot = findPackageRoot();\n\n  if (query && isFilePath(query)) {\n    readDocFile(packageRoot, query);\n    return;\n  }\n\n  const content = readLlmsTxt(packageRoot);\n\n  if (options.full) {\n    console.log(content.replaceAll(` ${COLLAPSED_MARKER}`, \"\"));\n    return;\n  }\n\n  const { header, sections } = parseSections(content);\n\n  if (query) {\n    const matched = findSections(sections, query);\n    if (matched.length === 0) {\n      const available = sections.map((s) => `  - ${s.name}`).join(\"\\n\");\n      console.error(\n        `No section matching \"${query}\". Available sections:\\n${available}`,\n      );\n      process.exit(1);\n    }\n    console.log(matched.map(formatExpandedSection).join(\"\\n\"));\n    return;\n  }\n\n  const output =\n    header +\n    sections\n      .map((s) =>\n        s.collapsed ? formatCollapsedSection(s) : formatExpandedSection(s),\n      )\n      .join(\"\\n\");\n  console.log(output);\n}\n\nexport const docsCommand = new Command(\"docs\")\n  .description(\"Display embedded documentation\")\n  .argument(\n    \"[query]\",\n    \"Section name (e.g. 'plugins') or path to a doc file (e.g. './docs.md')\",\n  )\n  .option(\"--full\", \"Show complete index including all API reference entries\")\n  .addHelpText(\n    \"after\",\n    `\nExamples:\n  $ appkit docs\n  $ appkit docs plugins\n  $ appkit docs \"appkit-ui API reference\"\n  $ appkit docs ./docs/plugins/analytics.md\n  $ appkit docs --full`,\n  )\n  .action(runDocs);\n"],"mappings":"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"}

package/dist/cli/commands/generate-types.js

@@ -13,19 +13,24 @@ async function runGenerateTypes(rootDir, outFile, warehouseId, options) {
 		const typeGen = await import("@databricks/appkit/type-generator");
 		const resolvedWarehouseId = warehouseId || process.env.DATABRICKS_WAREHOUSE_ID;
 		if (resolvedWarehouseId) {
-			const resolvedOutFile = outFile || path.join(process.cwd(), "client/src/appKitTypes.d.ts");
+			const resolvedOutFile = outFile || path.join(process.cwd(), "shared/appkit-types/analytics.d.ts");
 			const queryFolder = path.join(resolvedRootDir, "config/queries");
-			if (fs.existsSync(queryFolder)) await typeGen.generateFromEntryPoint({
-				queryFolder,
-				outFile: resolvedOutFile,
-				warehouseId: resolvedWarehouseId,
-				noCache
-			});
-		}
+			if (fs.existsSync(queryFolder)) {
+				await typeGen.generateFromEntryPoint({
+					queryFolder,
+					outFile: resolvedOutFile,
+					warehouseId: resolvedWarehouseId,
+					noCache
+				});
+				console.log(`Generated query types: ${resolvedOutFile}`);
+			}
+		} else console.error("Skipping query type generation: no warehouse ID. Set DATABRICKS_WAREHOUSE_ID or pass as argument.");
+		const servingOutFile = path.join(process.cwd(), "shared/appkit-types/serving.d.ts");
 		await typeGen.generateServingTypes({
-			outFile: path.join(process.cwd(), "client/src/appKitServingTypes.d.ts"),
+			outFile: servingOutFile,
 			noCache
 		});
+		console.log(`Generated serving types: ${servingOutFile}`);
 	} catch (error) {
 		if (error instanceof Error && error.message.includes("Cannot find module")) {
 			console.error("Error: The 'generate-types' command is only available in @databricks/appkit.");
@@ -35,7 +40,12 @@ async function runGenerateTypes(rootDir, outFile, warehouseId, options) {
 		throw error;
 	}
 }
-const generateTypesCommand = new Command("generate-types").description("Generate TypeScript types from SQL queries").argument("[rootDir]", "Root directory of the project", process.cwd()).argument("[outFile]", "Output file path", path.join(process.cwd(), "client/src/appKitTypes.d.ts")).argument("[warehouseId]", "Databricks warehouse ID").option("--no-cache", "Disable caching for type generation").action(runGenerateTypes);
+const generateTypesCommand = new Command("generate-types").description("Generate TypeScript types from SQL queries").argument("[rootDir]", "Root directory of the project", process.cwd()).argument("[outFile]", "Output file path", path.join(process.cwd(), "shared/appkit-types/analytics.d.ts")).argument("[warehouseId]", "Databricks warehouse ID").option("--no-cache", "Disable caching for type generation").addHelpText("after", `
+Examples:
+  $ appkit generate-types
+  $ appkit generate-types . shared/appkit-types/analytics.d.ts
+  $ appkit generate-types . shared/appkit-types/analytics.d.ts my-warehouse-id
+  $ appkit generate-types --no-cache`).action(runGenerateTypes);
 
 //#endregion
 export { generateTypesCommand };

package/dist/cli/commands/generate-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate-types.js","names":[],"sources":["../../../src/cli/commands/generate-types.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { Command } from \"commander\";\n\n/**\n * Generate types command implementation\n */\nasync function runGenerateTypes(\n  rootDir?: string,\n  outFile?: string,\n  warehouseId?: string,\n  options?: { noCache?: boolean },\n) {\n  try {\n    const resolvedRootDir = rootDir || process.cwd();\n    const noCache = options?.noCache || false;\n\n    const typeGen = await import(\"@databricks/appkit/type-generator\");\n\n    // Generate analytics query types (requires warehouse ID)\n    const resolvedWarehouseId =\n      warehouseId || process.env.DATABRICKS_WAREHOUSE_ID;\n\n    if (resolvedWarehouseId) {\n      const resolvedOutFile =\n        outFile || path.join(process.cwd(), \"client/src/appKitTypes.d.ts\");\n\n      const queryFolder = path.join(resolvedRootDir, \"config/queries\");\n      if (fs.existsSync(queryFolder)) {\n        await typeGen.generateFromEntryPoint({\n          queryFolder,\n          outFile: resolvedOutFile,\n          warehouseId: resolvedWarehouseId,\n          noCache,\n        });\n      }\n    }\n\n    // Generate serving endpoint types (no warehouse required)\n    await typeGen.generateServingTypes({\n      outFile: path.join(process.cwd(), \"client/src/appKitServingTypes.d.ts\"),\n      noCache,\n    });\n  } catch (error) {\n    if (\n      error instanceof Error &&\n      error.message.includes(\"Cannot find module\")\n    ) {\n      console.error(\n        \"Error: The 'generate-types' command is only available in @databricks/appkit.\",\n      );\n      console.error(\"Please install @databricks/appkit to use this command.\");\n      process.exit(1);\n    }\n    throw error;\n  }\n}\n\nexport const generateTypesCommand = new Command(\"generate-types\")\n  .description(\"Generate TypeScript types from SQL queries\")\n  .argument(\"[rootDir]\", \"Root directory of the project\", process.cwd())\n  .argument(\n    \"[outFile]\",\n    \"Output file path\",\n    path.join(process.cwd(), \"client/src/appKitTypes.d.ts\"),\n  )\n  .argument(\"[warehouseId]\", \"Databricks warehouse ID\")\n  .option(\"--no-cache\", \"Disable caching for type generation\")\n  .action(runGenerateTypes);\n"],"mappings":";;;;;;;;AAOA,eAAe,iBACb,SACA,SACA,aACA,SACA;AACA,KAAI;EACF,MAAM,kBAAkB,WAAW,QAAQ,KAAK;EAChD,MAAM,UAAU,SAAS,WAAW;EAEpC,MAAM,UAAU,MAAM,OAAO;EAG7B,MAAM,sBACJ,eAAe,QAAQ,IAAI;AAE7B,MAAI,qBAAqB;GACvB,MAAM,kBACJ,WAAW,KAAK,KAAK,QAAQ,KAAK,EAAE,8BAA8B;GAEpE,MAAM,cAAc,KAAK,KAAK,iBAAiB,iBAAiB;AAChE,OAAI,GAAG,WAAW,YAAY,CAC5B,OAAM,QAAQ,uBAAuB;IACnC;IACA,SAAS;IACT,aAAa;IACb;IACD,CAAC;;AAKN,QAAM,QAAQ,qBAAqB;GACjC,SAAS,KAAK,KAAK,QAAQ,KAAK,EAAE,qCAAqC;GACvE;GACD,CAAC;UACK,OAAO;AACd,MACE,iBAAiB,SACjB,MAAM,QAAQ,SAAS,qBAAqB,EAC5C;AACA,WAAQ,MACN,+EACD;AACD,WAAQ,MAAM,yDAAyD;AACvE,WAAQ,KAAK,EAAE;;AAEjB,QAAM;;;AAIV,MAAa,uBAAuB,IAAI,QAAQ,iBAAiB,CAC9D,YAAY,6CAA6C,CACzD,SAAS,aAAa,iCAAiC,QAAQ,KAAK,CAAC,CACrE,SACC,aACA,oBACA,KAAK,KAAK,QAAQ,KAAK,EAAE,8BAA8B,CACxD,CACA,SAAS,iBAAiB,0BAA0B,CACpD,OAAO,cAAc,sCAAsC,CAC3D,OAAO,iBAAiB"}
+{"version":3,"file":"generate-types.js","names":[],"sources":["../../../src/cli/commands/generate-types.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { Command } from \"commander\";\n\n/**\n * Generate types command implementation\n */\nasync function runGenerateTypes(\n  rootDir?: string,\n  outFile?: string,\n  warehouseId?: string,\n  options?: { noCache?: boolean },\n) {\n  try {\n    const resolvedRootDir = rootDir || process.cwd();\n    const noCache = options?.noCache || false;\n\n    const typeGen = await import(\"@databricks/appkit/type-generator\");\n\n    // Generate analytics query types (requires warehouse ID)\n    const resolvedWarehouseId =\n      warehouseId || process.env.DATABRICKS_WAREHOUSE_ID;\n\n    if (resolvedWarehouseId) {\n      const resolvedOutFile =\n        outFile ||\n        path.join(process.cwd(), \"shared/appkit-types/analytics.d.ts\");\n\n      const queryFolder = path.join(resolvedRootDir, \"config/queries\");\n      if (fs.existsSync(queryFolder)) {\n        await typeGen.generateFromEntryPoint({\n          queryFolder,\n          outFile: resolvedOutFile,\n          warehouseId: resolvedWarehouseId,\n          noCache,\n        });\n        console.log(`Generated query types: ${resolvedOutFile}`);\n      }\n    } else {\n      console.error(\n        \"Skipping query type generation: no warehouse ID. Set DATABRICKS_WAREHOUSE_ID or pass as argument.\",\n      );\n    }\n\n    // Generate serving endpoint types (no warehouse required)\n    const servingOutFile = path.join(\n      process.cwd(),\n      \"shared/appkit-types/serving.d.ts\",\n    );\n    await typeGen.generateServingTypes({\n      outFile: servingOutFile,\n      noCache,\n    });\n    console.log(`Generated serving types: ${servingOutFile}`);\n  } catch (error) {\n    if (\n      error instanceof Error &&\n      error.message.includes(\"Cannot find module\")\n    ) {\n      console.error(\n        \"Error: The 'generate-types' command is only available in @databricks/appkit.\",\n      );\n      console.error(\"Please install @databricks/appkit to use this command.\");\n      process.exit(1);\n    }\n    throw error;\n  }\n}\n\nexport const generateTypesCommand = new Command(\"generate-types\")\n  .description(\"Generate TypeScript types from SQL queries\")\n  .argument(\"[rootDir]\", \"Root directory of the project\", process.cwd())\n  .argument(\n    \"[outFile]\",\n    \"Output file path\",\n    path.join(process.cwd(), \"shared/appkit-types/analytics.d.ts\"),\n  )\n  .argument(\"[warehouseId]\", \"Databricks warehouse ID\")\n  .option(\"--no-cache\", \"Disable caching for type generation\")\n  .addHelpText(\n    \"after\",\n    `\nExamples:\n  $ appkit generate-types\n  $ appkit generate-types . shared/appkit-types/analytics.d.ts\n  $ appkit generate-types . shared/appkit-types/analytics.d.ts my-warehouse-id\n  $ appkit generate-types --no-cache`,\n  )\n  .action(runGenerateTypes);\n"],"mappings":";;;;;;;;AAOA,eAAe,iBACb,SACA,SACA,aACA,SACA;AACA,KAAI;EACF,MAAM,kBAAkB,WAAW,QAAQ,KAAK;EAChD,MAAM,UAAU,SAAS,WAAW;EAEpC,MAAM,UAAU,MAAM,OAAO;EAG7B,MAAM,sBACJ,eAAe,QAAQ,IAAI;AAE7B,MAAI,qBAAqB;GACvB,MAAM,kBACJ,WACA,KAAK,KAAK,QAAQ,KAAK,EAAE,qCAAqC;GAEhE,MAAM,cAAc,KAAK,KAAK,iBAAiB,iBAAiB;AAChE,OAAI,GAAG,WAAW,YAAY,EAAE;AAC9B,UAAM,QAAQ,uBAAuB;KACnC;KACA,SAAS;KACT,aAAa;KACb;KACD,CAAC;AACF,YAAQ,IAAI,0BAA0B,kBAAkB;;QAG1D,SAAQ,MACN,oGACD;EAIH,MAAM,iBAAiB,KAAK,KAC1B,QAAQ,KAAK,EACb,mCACD;AACD,QAAM,QAAQ,qBAAqB;GACjC,SAAS;GACT;GACD,CAAC;AACF,UAAQ,IAAI,4BAA4B,iBAAiB;UAClD,OAAO;AACd,MACE,iBAAiB,SACjB,MAAM,QAAQ,SAAS,qBAAqB,EAC5C;AACA,WAAQ,MACN,+EACD;AACD,WAAQ,MAAM,yDAAyD;AACvE,WAAQ,KAAK,EAAE;;AAEjB,QAAM;;;AAIV,MAAa,uBAAuB,IAAI,QAAQ,iBAAiB,CAC9D,YAAY,6CAA6C,CACzD,SAAS,aAAa,iCAAiC,QAAQ,KAAK,CAAC,CACrE,SACC,aACA,oBACA,KAAK,KAAK,QAAQ,KAAK,EAAE,qCAAqC,CAC/D,CACA,SAAS,iBAAiB,0BAA0B,CACpD,OAAO,cAAc,sCAAsC,CAC3D,YACC,SACA;;;;;sCAMD,CACA,OAAO,iBAAiB"}

package/dist/cli/commands/lint.js

@@ -97,7 +97,9 @@ function runLint() {
 	}
 	process.exit(1);
 }
-const lintCommand = new Command("lint").description("Run AST-based linting on TypeScript files").action(runLint);
+const lintCommand = new Command("lint").description("Run AST-based linting on TypeScript files").addHelpText("after", `
+Examples:
+  $ appkit lint`).action(runLint);
 
 //#endregion
 export { lintCommand };

package/dist/cli/commands/lint.js.map

@@ -1 +1 @@
-{"version":3,"file":"lint.js","names":[],"sources":["../../../src/cli/commands/lint.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { Lang, parse } from \"@ast-grep/napi\";\nimport { Command } from \"commander\";\n\ninterface Rule {\n  id: string;\n  pattern: string;\n  message: string;\n  includeTests?: boolean;\n  filter?: (code: string) => boolean;\n}\n\nconst rules: Rule[] = [\n  {\n    id: \"no-double-type-assertion\",\n    pattern: \"$X as unknown as $Y\",\n    message:\n      \"Avoid double type assertion (as unknown as). Use proper type guards or fix the source type.\",\n  },\n  {\n    id: \"no-as-any\",\n    pattern: \"$X as any\",\n    message:\n      'Avoid \"as any\" type assertion. Use proper typing or unknown with type guards.',\n    includeTests: false, // acceptable in test mocks\n  },\n  {\n    id: \"no-array-index-key\",\n    pattern: \"key={$IDX}\",\n    message:\n      \"Avoid using array index as React key. Use a stable unique identifier.\",\n    filter: (code) => /key=\\{(idx|index|i)\\}/.test(code),\n  },\n  {\n    id: \"no-parse-float-without-validation\",\n    pattern: \"parseFloat($X).toFixed($Y)\",\n    message:\n      \"parseFloat can return NaN. Validate input or use toNumber() helper from shared/types.ts.\",\n  },\n];\n\nfunction isTestFile(filePath: string): boolean {\n  return (\n    /\\.(test|spec)\\.(ts|tsx)$/.test(filePath) || filePath.includes(\"/tests/\")\n  );\n}\n\nfunction findTsFiles(dir: string, files: string[] = []): string[] {\n  const entries = fs.readdirSync(dir, { withFileTypes: true });\n\n  for (const entry of entries) {\n    const fullPath = path.join(dir, entry.name);\n\n    if (entry.isDirectory()) {\n      if ([\"node_modules\", \"dist\", \"build\", \".git\"].includes(entry.name))\n        continue;\n      findTsFiles(fullPath, files);\n    } else if (entry.isFile() && /\\.(ts|tsx)$/.test(entry.name)) {\n      files.push(fullPath);\n    }\n  }\n\n  return files;\n}\n\ninterface Violation {\n  file: string;\n  line: number;\n  column: number;\n  rule: string;\n  message: string;\n  code: string;\n}\n\nfunction lintFile(filePath: string, rules: Rule[]): Violation[] {\n  const violations: Violation[] = [];\n  const content = fs.readFileSync(filePath, \"utf-8\");\n  const lang = filePath.endsWith(\".tsx\") ? Lang.Tsx : Lang.TypeScript;\n  const testFile = isTestFile(filePath);\n\n  const ast = parse(lang, content);\n  const root = ast.root();\n\n  for (const rule of rules) {\n    // skip rules that don't apply to test files\n    if (testFile && rule.includeTests === false) continue;\n\n    const matches = root.findAll(rule.pattern);\n\n    for (const match of matches) {\n      const code = match.text();\n\n      if (rule.filter && !rule.filter(code)) continue;\n\n      const range = match.range();\n      violations.push({\n        file: filePath,\n        line: range.start.line + 1,\n        column: range.start.column + 1,\n        rule: rule.id,\n        message: rule.message,\n        code: code.length > 80 ? `${code.slice(0, 77)}...` : code,\n      });\n    }\n  }\n\n  return violations;\n}\n\n/**\n * Lint command implementation\n */\nfunction runLint() {\n  const rootDir = process.cwd();\n  const files = findTsFiles(rootDir);\n\n  console.log(`Scanning ${files.length} TypeScript files...\\n`);\n\n  const allViolations: Violation[] = [];\n\n  for (const file of files) {\n    const violations = lintFile(file, rules);\n    allViolations.push(...violations);\n  }\n\n  if (allViolations.length === 0) {\n    console.log(\"No ast-grep lint violations found.\");\n    process.exit(0);\n  }\n\n  console.log(`Found ${allViolations.length} violation(s):\\n`);\n\n  for (const v of allViolations) {\n    const relPath = path.relative(rootDir, v.file);\n    console.log(`${relPath}:${v.line}:${v.column}`);\n    console.log(`  ${v.rule}: ${v.message}`);\n    console.log(`  > ${v.code}\\n`);\n  }\n\n  process.exit(1);\n}\n\nexport const lintCommand = new Command(\"lint\")\n  .description(\"Run AST-based linting on TypeScript files\")\n  .action(runLint);\n"],"mappings":";;;;;;AAaA,MAAM,QAAgB;CACpB;EACE,IAAI;EACJ,SAAS;EACT,SACE;EACH;CACD;EACE,IAAI;EACJ,SAAS;EACT,SACE;EACF,cAAc;EACf;CACD;EACE,IAAI;EACJ,SAAS;EACT,SACE;EACF,SAAS,SAAS,wBAAwB,KAAK,KAAK;EACrD;CACD;EACE,IAAI;EACJ,SAAS;EACT,SACE;EACH;CACF;AAED,SAAS,WAAW,UAA2B;AAC7C,QACE,2BAA2B,KAAK,SAAS,IAAI,SAAS,SAAS,UAAU;;AAI7E,SAAS,YAAY,KAAa,QAAkB,EAAE,EAAY;CAChE,MAAM,UAAU,GAAG,YAAY,KAAK,EAAE,eAAe,MAAM,CAAC;AAE5D,MAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,WAAW,KAAK,KAAK,KAAK,MAAM,KAAK;AAE3C,MAAI,MAAM,aAAa,EAAE;AACvB,OAAI;IAAC;IAAgB;IAAQ;IAAS;IAAO,CAAC,SAAS,MAAM,KAAK,CAChE;AACF,eAAY,UAAU,MAAM;aACnB,MAAM,QAAQ,IAAI,cAAc,KAAK,MAAM,KAAK,CACzD,OAAM,KAAK,SAAS;;AAIxB,QAAO;;AAYT,SAAS,SAAS,UAAkB,OAA4B;CAC9D,MAAM,aAA0B,EAAE;CAClC,MAAM,UAAU,GAAG,aAAa,UAAU,QAAQ;CAClD,MAAM,OAAO,SAAS,SAAS,OAAO,GAAG,KAAK,MAAM,KAAK;CACzD,MAAM,WAAW,WAAW,SAAS;CAGrC,MAAM,OADM,MAAM,MAAM,QAAQ,CACf,MAAM;AAEvB,MAAK,MAAM,QAAQ,OAAO;AAExB,MAAI,YAAY,KAAK,iBAAiB,MAAO;EAE7C,MAAM,UAAU,KAAK,QAAQ,KAAK,QAAQ;AAE1C,OAAK,MAAM,SAAS,SAAS;GAC3B,MAAM,OAAO,MAAM,MAAM;AAEzB,OAAI,KAAK,UAAU,CAAC,KAAK,OAAO,KAAK,CAAE;GAEvC,MAAM,QAAQ,MAAM,OAAO;AAC3B,cAAW,KAAK;IACd,MAAM;IACN,MAAM,MAAM,MAAM,OAAO;IACzB,QAAQ,MAAM,MAAM,SAAS;IAC7B,MAAM,KAAK;IACX,SAAS,KAAK;IACd,MAAM,KAAK,SAAS,KAAK,GAAG,KAAK,MAAM,GAAG,GAAG,CAAC,OAAO;IACtD,CAAC;;;AAIN,QAAO;;;;;AAMT,SAAS,UAAU;CACjB,MAAM,UAAU,QAAQ,KAAK;CAC7B,MAAM,QAAQ,YAAY,QAAQ;AAElC,SAAQ,IAAI,YAAY,MAAM,OAAO,wBAAwB;CAE7D,MAAM,gBAA6B,EAAE;AAErC,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,aAAa,SAAS,MAAM,MAAM;AACxC,gBAAc,KAAK,GAAG,WAAW;;AAGnC,KAAI,cAAc,WAAW,GAAG;AAC9B,UAAQ,IAAI,qCAAqC;AACjD,UAAQ,KAAK,EAAE;;AAGjB,SAAQ,IAAI,SAAS,cAAc,OAAO,kBAAkB;AAE5D,MAAK,MAAM,KAAK,eAAe;EAC7B,MAAM,UAAU,KAAK,SAAS,SAAS,EAAE,KAAK;AAC9C,UAAQ,IAAI,GAAG,QAAQ,GAAG,EAAE,KAAK,GAAG,EAAE,SAAS;AAC/C,UAAQ,IAAI,KAAK,EAAE,KAAK,IAAI,EAAE,UAAU;AACxC,UAAQ,IAAI,OAAO,EAAE,KAAK,IAAI;;AAGhC,SAAQ,KAAK,EAAE;;AAGjB,MAAa,cAAc,IAAI,QAAQ,OAAO,CAC3C,YAAY,4CAA4C,CACxD,OAAO,QAAQ"}
+{"version":3,"file":"lint.js","names":[],"sources":["../../../src/cli/commands/lint.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { Lang, parse } from \"@ast-grep/napi\";\nimport { Command } from \"commander\";\n\ninterface Rule {\n  id: string;\n  pattern: string;\n  message: string;\n  includeTests?: boolean;\n  filter?: (code: string) => boolean;\n}\n\nconst rules: Rule[] = [\n  {\n    id: \"no-double-type-assertion\",\n    pattern: \"$X as unknown as $Y\",\n    message:\n      \"Avoid double type assertion (as unknown as). Use proper type guards or fix the source type.\",\n  },\n  {\n    id: \"no-as-any\",\n    pattern: \"$X as any\",\n    message:\n      'Avoid \"as any\" type assertion. Use proper typing or unknown with type guards.',\n    includeTests: false, // acceptable in test mocks\n  },\n  {\n    id: \"no-array-index-key\",\n    pattern: \"key={$IDX}\",\n    message:\n      \"Avoid using array index as React key. Use a stable unique identifier.\",\n    filter: (code) => /key=\\{(idx|index|i)\\}/.test(code),\n  },\n  {\n    id: \"no-parse-float-without-validation\",\n    pattern: \"parseFloat($X).toFixed($Y)\",\n    message:\n      \"parseFloat can return NaN. Validate input or use toNumber() helper from shared/types.ts.\",\n  },\n];\n\nfunction isTestFile(filePath: string): boolean {\n  return (\n    /\\.(test|spec)\\.(ts|tsx)$/.test(filePath) || filePath.includes(\"/tests/\")\n  );\n}\n\nfunction findTsFiles(dir: string, files: string[] = []): string[] {\n  const entries = fs.readdirSync(dir, { withFileTypes: true });\n\n  for (const entry of entries) {\n    const fullPath = path.join(dir, entry.name);\n\n    if (entry.isDirectory()) {\n      if ([\"node_modules\", \"dist\", \"build\", \".git\"].includes(entry.name))\n        continue;\n      findTsFiles(fullPath, files);\n    } else if (entry.isFile() && /\\.(ts|tsx)$/.test(entry.name)) {\n      files.push(fullPath);\n    }\n  }\n\n  return files;\n}\n\ninterface Violation {\n  file: string;\n  line: number;\n  column: number;\n  rule: string;\n  message: string;\n  code: string;\n}\n\nfunction lintFile(filePath: string, rules: Rule[]): Violation[] {\n  const violations: Violation[] = [];\n  const content = fs.readFileSync(filePath, \"utf-8\");\n  const lang = filePath.endsWith(\".tsx\") ? Lang.Tsx : Lang.TypeScript;\n  const testFile = isTestFile(filePath);\n\n  const ast = parse(lang, content);\n  const root = ast.root();\n\n  for (const rule of rules) {\n    // skip rules that don't apply to test files\n    if (testFile && rule.includeTests === false) continue;\n\n    const matches = root.findAll(rule.pattern);\n\n    for (const match of matches) {\n      const code = match.text();\n\n      if (rule.filter && !rule.filter(code)) continue;\n\n      const range = match.range();\n      violations.push({\n        file: filePath,\n        line: range.start.line + 1,\n        column: range.start.column + 1,\n        rule: rule.id,\n        message: rule.message,\n        code: code.length > 80 ? `${code.slice(0, 77)}...` : code,\n      });\n    }\n  }\n\n  return violations;\n}\n\n/**\n * Lint command implementation\n */\nfunction runLint() {\n  const rootDir = process.cwd();\n  const files = findTsFiles(rootDir);\n\n  console.log(`Scanning ${files.length} TypeScript files...\\n`);\n\n  const allViolations: Violation[] = [];\n\n  for (const file of files) {\n    const violations = lintFile(file, rules);\n    allViolations.push(...violations);\n  }\n\n  if (allViolations.length === 0) {\n    console.log(\"No ast-grep lint violations found.\");\n    process.exit(0);\n  }\n\n  console.log(`Found ${allViolations.length} violation(s):\\n`);\n\n  for (const v of allViolations) {\n    const relPath = path.relative(rootDir, v.file);\n    console.log(`${relPath}:${v.line}:${v.column}`);\n    console.log(`  ${v.rule}: ${v.message}`);\n    console.log(`  > ${v.code}\\n`);\n  }\n\n  process.exit(1);\n}\n\nexport const lintCommand = new Command(\"lint\")\n  .description(\"Run AST-based linting on TypeScript files\")\n  .addHelpText(\n    \"after\",\n    `\nExamples:\n  $ appkit lint`,\n  )\n  .action(runLint);\n"],"mappings":";;;;;;AAaA,MAAM,QAAgB;CACpB;EACE,IAAI;EACJ,SAAS;EACT,SACE;EACH;CACD;EACE,IAAI;EACJ,SAAS;EACT,SACE;EACF,cAAc;EACf;CACD;EACE,IAAI;EACJ,SAAS;EACT,SACE;EACF,SAAS,SAAS,wBAAwB,KAAK,KAAK;EACrD;CACD;EACE,IAAI;EACJ,SAAS;EACT,SACE;EACH;CACF;AAED,SAAS,WAAW,UAA2B;AAC7C,QACE,2BAA2B,KAAK,SAAS,IAAI,SAAS,SAAS,UAAU;;AAI7E,SAAS,YAAY,KAAa,QAAkB,EAAE,EAAY;CAChE,MAAM,UAAU,GAAG,YAAY,KAAK,EAAE,eAAe,MAAM,CAAC;AAE5D,MAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,WAAW,KAAK,KAAK,KAAK,MAAM,KAAK;AAE3C,MAAI,MAAM,aAAa,EAAE;AACvB,OAAI;IAAC;IAAgB;IAAQ;IAAS;IAAO,CAAC,SAAS,MAAM,KAAK,CAChE;AACF,eAAY,UAAU,MAAM;aACnB,MAAM,QAAQ,IAAI,cAAc,KAAK,MAAM,KAAK,CACzD,OAAM,KAAK,SAAS;;AAIxB,QAAO;;AAYT,SAAS,SAAS,UAAkB,OAA4B;CAC9D,MAAM,aAA0B,EAAE;CAClC,MAAM,UAAU,GAAG,aAAa,UAAU,QAAQ;CAClD,MAAM,OAAO,SAAS,SAAS,OAAO,GAAG,KAAK,MAAM,KAAK;CACzD,MAAM,WAAW,WAAW,SAAS;CAGrC,MAAM,OADM,MAAM,MAAM,QAAQ,CACf,MAAM;AAEvB,MAAK,MAAM,QAAQ,OAAO;AAExB,MAAI,YAAY,KAAK,iBAAiB,MAAO;EAE7C,MAAM,UAAU,KAAK,QAAQ,KAAK,QAAQ;AAE1C,OAAK,MAAM,SAAS,SAAS;GAC3B,MAAM,OAAO,MAAM,MAAM;AAEzB,OAAI,KAAK,UAAU,CAAC,KAAK,OAAO,KAAK,CAAE;GAEvC,MAAM,QAAQ,MAAM,OAAO;AAC3B,cAAW,KAAK;IACd,MAAM;IACN,MAAM,MAAM,MAAM,OAAO;IACzB,QAAQ,MAAM,MAAM,SAAS;IAC7B,MAAM,KAAK;IACX,SAAS,KAAK;IACd,MAAM,KAAK,SAAS,KAAK,GAAG,KAAK,MAAM,GAAG,GAAG,CAAC,OAAO;IACtD,CAAC;;;AAIN,QAAO;;;;;AAMT,SAAS,UAAU;CACjB,MAAM,UAAU,QAAQ,KAAK;CAC7B,MAAM,QAAQ,YAAY,QAAQ;AAElC,SAAQ,IAAI,YAAY,MAAM,OAAO,wBAAwB;CAE7D,MAAM,gBAA6B,EAAE;AAErC,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,aAAa,SAAS,MAAM,MAAM;AACxC,gBAAc,KAAK,GAAG,WAAW;;AAGnC,KAAI,cAAc,WAAW,GAAG;AAC9B,UAAQ,IAAI,qCAAqC;AACjD,UAAQ,KAAK,EAAE;;AAGjB,SAAQ,IAAI,SAAS,cAAc,OAAO,kBAAkB;AAE5D,MAAK,MAAM,KAAK,eAAe;EAC7B,MAAM,UAAU,KAAK,SAAS,SAAS,EAAE,KAAK;AAC9C,UAAQ,IAAI,GAAG,QAAQ,GAAG,EAAE,KAAK,GAAG,EAAE,SAAS;AAC/C,UAAQ,IAAI,KAAK,EAAE,KAAK,IAAI,EAAE,UAAU;AACxC,UAAQ,IAAI,OAAO,EAAE,KAAK,IAAI;;AAGhC,SAAQ,KAAK,EAAE;;AAGjB,MAAa,cAAc,IAAI,QAAQ,OAAO,CAC3C,YAAY,4CAA4C,CACxD,YACC,SACA;;iBAGD,CACA,OAAO,QAAQ"}

package/dist/cli/commands/plugin/add-resource/add-resource.js

@@ -1,4 +1,4 @@
-import { humanizeResourceType } from "../create/resource-defaults.js";
+import { DEFAULT_PERMISSION_BY_TYPE, getDefaultFieldsForType, getValidResourceTypes, humanizeResourceType, resourceKeyFromType } from "../create/resource-defaults.js";
 import { promptOneResource } from "../create/prompt-resource.js";
 import { resolveManifestInDir } from "../manifest-resolve.js";
 import { validateManifest } from "../validate/validate-manifest.js";
@@ -9,13 +9,11 @@ import process from "node:process";
 import { cancel, intro, outro } from "@clack/prompts";
 
 //#region src/cli/commands/plugin/add-resource/add-resource.ts
-async function runPluginAddResource(options) {
-	intro("Add resource to plugin manifest");
-	const cwd = process.cwd();
-	const pluginDir = path.resolve(cwd, options.path ?? ".");
+function loadManifest(pluginDir) {
 	const resolved = resolveManifestInDir(pluginDir, { allowJsManifest: true });
 	if (!resolved) {
 		console.error(`No manifest found in ${pluginDir}. This command requires manifest.json (manifest.js cannot be edited in place).`);
+		console.error("  appkit plugin add-resource --path <dir-with-manifest.json>");
 		process.exit(1);
 	}
 	if (resolved.type !== "json") {
@@ -23,7 +21,6 @@ async function runPluginAddResource(options) {
 		process.exit(1);
 	}
 	const manifestPath = resolved.path;
-	let manifest;
 	try {
 		const raw = fs.readFileSync(manifestPath, "utf-8");
 		const parsed = JSON.parse(raw);
@@ -32,11 +29,70 @@ async function runPluginAddResource(options) {
 			console.error("Invalid manifest. Run `appkit plugin validate` for details.");
 			process.exit(1);
 		}
-		manifest = parsed;
+		return {
+			manifest: parsed,
+			manifestPath
+		};
 	} catch (err) {
 		console.error("Failed to read or parse manifest.json:", err instanceof Error ? err.message : err);
 		process.exit(1);
 	}
+}
+function buildEntry(type, opts) {
+	const alias = humanizeResourceType(type);
+	const isRequired = opts.required !== false;
+	let fields = getDefaultFieldsForType(type);
+	if (opts.fieldsJson) try {
+		const parsed = JSON.parse(opts.fieldsJson);
+		fields = {
+			...fields,
+			...parsed
+		};
+	} catch {
+		console.error("Error: --fields-json must be valid JSON.");
+		console.error("  Example: --fields-json '{\"id\":{\"env\":\"MY_WAREHOUSE_ID\"}}'");
+		process.exit(1);
+	}
+	return {
+		entry: {
+			type,
+			alias,
+			resourceKey: opts.resourceKey ?? resourceKeyFromType(type),
+			description: opts.description || `${isRequired ? "Required" : "Optional"} for ${alias} functionality.`,
+			permission: opts.permission ?? DEFAULT_PERMISSION_BY_TYPE[type] ?? "CAN_VIEW",
+			fields
+		},
+		isRequired
+	};
+}
+function runNonInteractive(opts) {
+	const cwd = process.cwd();
+	const loaded = loadManifest(path.resolve(cwd, opts.path ?? "."));
+	if (!loaded) return;
+	const { manifest, manifestPath } = loaded;
+	const type = opts.type;
+	const validTypes = getValidResourceTypes();
+	if (!validTypes.includes(type)) {
+		console.error(`Error: Unknown resource type "${type}".`);
+		console.error(`  Valid types: ${validTypes.join(", ")}`);
+		process.exit(1);
+	}
+	const { entry, isRequired } = buildEntry(type, opts);
+	if (isRequired) manifest.resources.required.push(entry);
+	else manifest.resources.optional.push(entry);
+	if (opts.dryRun) {
+		console.log(JSON.stringify(manifest, null, 2));
+		return;
+	}
+	fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+	console.log(`Added ${entry.alias} as ${isRequired ? "required" : "optional"} to ${path.relative(cwd, manifestPath)}`);
+}
+async function runInteractive(opts) {
+	intro("Add resource to plugin manifest");
+	const cwd = process.cwd();
+	const loaded = loadManifest(path.resolve(cwd, opts.path ?? "."));
+	if (!loaded) return;
+	const { manifest, manifestPath } = loaded;
 	const spec = await promptOneResource();
 	if (!spec) {
 		cancel("Cancelled.");
@@ -57,7 +113,16 @@ async function runPluginAddResource(options) {
 	outro("Resource added.");
 	console.log(`\nAdded ${alias} as ${spec.required ? "required" : "optional"} to ${path.relative(cwd, manifestPath)}`);
 }
-const pluginAddResourceCommand = new Command("add-resource").description("Add a resource requirement to an existing plugin manifest (interactive). Overwrites manifest.json in place.").option("-p, --path <dir>", "Plugin directory containing manifest.json, which will be edited in place (default: .)").action((opts) => runPluginAddResource(opts).catch((err) => {
+async function runPluginAddResource(opts) {
+	if (opts.type) runNonInteractive(opts);
+	else await runInteractive(opts);
+}
+const pluginAddResourceCommand = new Command("add-resource").description("Add a resource requirement to an existing plugin manifest. Overwrites manifest.json in place.").option("-p, --path <dir>", "Plugin directory containing manifest.json (default: .)").option("-t, --type <resource_type>", "Resource type (e.g. sql_warehouse, volume). Enables non-interactive mode.").option("--required", "Mark resource as required (default: true)", true).option("--no-required", "Mark resource as optional").option("--resource-key <key>", "Resource key (default: derived from type)").option("--description <text>", "Description of the resource requirement").option("--permission <perm>", "Permission level (default: from schema)").option("--fields-json <json>", "JSON object overriding field env vars (e.g. '{\"id\":{\"env\":\"MY_WAREHOUSE_ID\"}}')").option("--dry-run", "Preview the updated manifest without writing").addHelpText("after", `
+Examples:
+  $ appkit plugin add-resource
+  $ appkit plugin add-resource --path plugins/my-plugin --type sql_warehouse
+  $ appkit plugin add-resource --path plugins/my-plugin --type volume --no-required --dry-run
+  $ appkit plugin add-resource --type sql_warehouse --fields-json '{"id":{"env":"MY_WAREHOUSE_ID"}}'`).action((opts) => runPluginAddResource(opts).catch((err) => {
 	console.error(err);
 	process.exit(1);
 }));

package/dist/cli/commands/plugin/add-resource/add-resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"add-resource.js","names":[],"sources":["../../../../../src/cli/commands/plugin/add-resource/add-resource.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport process from \"node:process\";\nimport { cancel, intro, outro } from \"@clack/prompts\";\nimport { Command } from \"commander\";\nimport { promptOneResource } from \"../create/prompt-resource\";\nimport { humanizeResourceType } from \"../create/resource-defaults\";\nimport { resolveManifestInDir } from \"../manifest-resolve\";\nimport type { PluginManifest, ResourceRequirement } from \"../manifest-types\";\nimport { validateManifest } from \"../validate/validate-manifest\";\n\n/** Extended manifest type that preserves extra JSON fields (e.g. $schema, author, version) for round-trip writes. */\ninterface ManifestWithExtras extends PluginManifest {\n  [key: string]: unknown;\n}\n\nasync function runPluginAddResource(options: { path?: string }): Promise<void> {\n  intro(\"Add resource to plugin manifest\");\n\n  const cwd = process.cwd();\n  const pluginDir = path.resolve(cwd, options.path ?? \".\");\n  const resolved = resolveManifestInDir(pluginDir, { allowJsManifest: true });\n\n  if (!resolved) {\n    console.error(\n      `No manifest found in ${pluginDir}. This command requires manifest.json (manifest.js cannot be edited in place).`,\n    );\n    process.exit(1);\n  }\n\n  if (resolved.type !== \"json\") {\n    console.error(\n      `Editable manifest not found. add-resource only supports plugin directories that contain manifest.json (found ${path.basename(resolved.path)}).`,\n    );\n    process.exit(1);\n  }\n\n  const manifestPath = resolved.path;\n\n  let manifest: ManifestWithExtras;\n  try {\n    const raw = fs.readFileSync(manifestPath, \"utf-8\");\n    const parsed = JSON.parse(raw) as unknown;\n    const result = validateManifest(parsed);\n    if (!result.valid || !result.manifest) {\n      console.error(\n        \"Invalid manifest. Run `appkit plugin validate` for details.\",\n      );\n      process.exit(1);\n    }\n    manifest = parsed as ManifestWithExtras;\n  } catch (err) {\n    console.error(\n      \"Failed to read or parse manifest.json:\",\n      err instanceof Error ? err.message : err,\n    );\n    process.exit(1);\n  }\n\n  const spec = await promptOneResource();\n  if (!spec) {\n    cancel(\"Cancelled.\");\n    process.exit(0);\n  }\n\n  const alias = humanizeResourceType(spec.type);\n  const entry: ResourceRequirement = {\n    // Safe cast: spec.type comes from RESOURCE_TYPE_OPTIONS which reads values\n    // from the same JSON schema that generates the ResourceType union.\n    type: spec.type as ResourceRequirement[\"type\"],\n    alias,\n    resourceKey: spec.resourceKey,\n    description: spec.description || `Required for ${alias} functionality.`,\n    permission: spec.permission,\n    fields: spec.fields,\n  };\n\n  if (spec.required) {\n    manifest.resources.required.push(entry);\n  } else {\n    manifest.resources.optional.push(entry);\n  }\n\n  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\\n`);\n\n  outro(\"Resource added.\");\n  console.log(\n    `\\nAdded ${alias} as ${spec.required ? \"required\" : \"optional\"} to ${path.relative(cwd, manifestPath)}`,\n  );\n}\n\nexport const pluginAddResourceCommand = new Command(\"add-resource\")\n  .description(\n    \"Add a resource requirement to an existing plugin manifest (interactive). Overwrites manifest.json in place.\",\n  )\n  .option(\n    \"-p, --path <dir>\",\n    \"Plugin directory containing manifest.json, which will be edited in place (default: .)\",\n  )\n  .action((opts) =>\n    runPluginAddResource(opts).catch((err) => {\n      console.error(err);\n      process.exit(1);\n    }),\n  );\n"],"mappings":";;;;;;;;;;;AAgBA,eAAe,qBAAqB,SAA2C;AAC7E,OAAM,kCAAkC;CAExC,MAAM,MAAM,QAAQ,KAAK;CACzB,MAAM,YAAY,KAAK,QAAQ,KAAK,QAAQ,QAAQ,IAAI;CACxD,MAAM,WAAW,qBAAqB,WAAW,EAAE,iBAAiB,MAAM,CAAC;AAE3E,KAAI,CAAC,UAAU;AACb,UAAQ,MACN,wBAAwB,UAAU,gFACnC;AACD,UAAQ,KAAK,EAAE;;AAGjB,KAAI,SAAS,SAAS,QAAQ;AAC5B,UAAQ,MACN,gHAAgH,KAAK,SAAS,SAAS,KAAK,CAAC,IAC9I;AACD,UAAQ,KAAK,EAAE;;CAGjB,MAAM,eAAe,SAAS;CAE9B,IAAI;AACJ,KAAI;EACF,MAAM,MAAM,GAAG,aAAa,cAAc,QAAQ;EAClD,MAAM,SAAS,KAAK,MAAM,IAAI;EAC9B,MAAM,SAAS,iBAAiB,OAAO;AACvC,MAAI,CAAC,OAAO,SAAS,CAAC,OAAO,UAAU;AACrC,WAAQ,MACN,8DACD;AACD,WAAQ,KAAK,EAAE;;AAEjB,aAAW;UACJ,KAAK;AACZ,UAAQ,MACN,0CACA,eAAe,QAAQ,IAAI,UAAU,IACtC;AACD,UAAQ,KAAK,EAAE;;CAGjB,MAAM,OAAO,MAAM,mBAAmB;AACtC,KAAI,CAAC,MAAM;AACT,SAAO,aAAa;AACpB,UAAQ,KAAK,EAAE;;CAGjB,MAAM,QAAQ,qBAAqB,KAAK,KAAK;CAC7C,MAAM,QAA6B;EAGjC,MAAM,KAAK;EACX;EACA,aAAa,KAAK;EAClB,aAAa,KAAK,eAAe,gBAAgB,MAAM;EACvD,YAAY,KAAK;EACjB,QAAQ,KAAK;EACd;AAED,KAAI,KAAK,SACP,UAAS,UAAU,SAAS,KAAK,MAAM;KAEvC,UAAS,UAAU,SAAS,KAAK,MAAM;AAGzC,IAAG,cAAc,cAAc,GAAG,KAAK,UAAU,UAAU,MAAM,EAAE,CAAC,IAAI;AAExE,OAAM,kBAAkB;AACxB,SAAQ,IACN,WAAW,MAAM,MAAM,KAAK,WAAW,aAAa,WAAW,MAAM,KAAK,SAAS,KAAK,aAAa,GACtG;;AAGH,MAAa,2BAA2B,IAAI,QAAQ,eAAe,CAChE,YACC,8GACD,CACA,OACC,oBACA,wFACD,CACA,QAAQ,SACP,qBAAqB,KAAK,CAAC,OAAO,QAAQ;AACxC,SAAQ,MAAM,IAAI;AAClB,SAAQ,KAAK,EAAE;EACf,CACH"}
+{"version":3,"file":"add-resource.js","names":[],"sources":["../../../../../src/cli/commands/plugin/add-resource/add-resource.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport process from \"node:process\";\nimport { cancel, intro, outro } from \"@clack/prompts\";\nimport { Command } from \"commander\";\nimport { promptOneResource } from \"../create/prompt-resource\";\nimport {\n  DEFAULT_PERMISSION_BY_TYPE,\n  getDefaultFieldsForType,\n  getValidResourceTypes,\n  humanizeResourceType,\n  resourceKeyFromType,\n} from \"../create/resource-defaults\";\nimport { resolveManifestInDir } from \"../manifest-resolve\";\nimport type { PluginManifest, ResourceRequirement } from \"../manifest-types\";\nimport { validateManifest } from \"../validate/validate-manifest\";\n\n/** Extended manifest type that preserves extra JSON fields (e.g. $schema, author, version) for round-trip writes. */\ninterface ManifestWithExtras extends PluginManifest {\n  [key: string]: unknown;\n}\n\ninterface AddResourceOptions {\n  path?: string;\n  type?: string;\n  required?: boolean;\n  resourceKey?: string;\n  description?: string;\n  permission?: string;\n  fieldsJson?: string;\n  dryRun?: boolean;\n}\n\nfunction loadManifest(\n  pluginDir: string,\n): { manifest: ManifestWithExtras; manifestPath: string } | null {\n  const resolved = resolveManifestInDir(pluginDir, { allowJsManifest: true });\n\n  if (!resolved) {\n    console.error(\n      `No manifest found in ${pluginDir}. This command requires manifest.json (manifest.js cannot be edited in place).`,\n    );\n    console.error(\n      \"  appkit plugin add-resource --path <dir-with-manifest.json>\",\n    );\n    process.exit(1);\n  }\n\n  if (resolved.type !== \"json\") {\n    console.error(\n      `Editable manifest not found. add-resource only supports plugin directories that contain manifest.json (found ${path.basename(resolved.path)}).`,\n    );\n    process.exit(1);\n  }\n\n  const manifestPath = resolved.path;\n\n  try {\n    const raw = fs.readFileSync(manifestPath, \"utf-8\");\n    const parsed = JSON.parse(raw) as unknown;\n    const result = validateManifest(parsed);\n    if (!result.valid || !result.manifest) {\n      console.error(\n        \"Invalid manifest. Run `appkit plugin validate` for details.\",\n      );\n      process.exit(1);\n    }\n    return { manifest: parsed as ManifestWithExtras, manifestPath };\n  } catch (err) {\n    console.error(\n      \"Failed to read or parse manifest.json:\",\n      err instanceof Error ? err.message : err,\n    );\n    process.exit(1);\n  }\n}\n\nfunction buildEntry(\n  type: string,\n  opts: AddResourceOptions,\n): { entry: ResourceRequirement; isRequired: boolean } {\n  const alias = humanizeResourceType(type);\n  const isRequired = opts.required !== false;\n\n  let fields = getDefaultFieldsForType(type);\n  if (opts.fieldsJson) {\n    try {\n      const parsed = JSON.parse(opts.fieldsJson) as Record<\n        string,\n        { env: string; description?: string }\n      >;\n      fields = { ...fields, ...parsed };\n    } catch {\n      console.error(\"Error: --fields-json must be valid JSON.\");\n      console.error(\n        '  Example: --fields-json \\'{\"id\":{\"env\":\"MY_WAREHOUSE_ID\"}}\\'',\n      );\n      process.exit(1);\n    }\n  }\n\n  const entry: ResourceRequirement = {\n    type: type as ResourceRequirement[\"type\"],\n    alias,\n    resourceKey: opts.resourceKey ?? resourceKeyFromType(type),\n    description:\n      opts.description ||\n      `${isRequired ? \"Required\" : \"Optional\"} for ${alias} functionality.`,\n    permission:\n      opts.permission ?? DEFAULT_PERMISSION_BY_TYPE[type] ?? \"CAN_VIEW\",\n    fields,\n  };\n\n  return { entry, isRequired };\n}\n\nfunction runNonInteractive(opts: AddResourceOptions): void {\n  const cwd = process.cwd();\n  const pluginDir = path.resolve(cwd, opts.path ?? \".\");\n  const loaded = loadManifest(pluginDir);\n  if (!loaded) return;\n  const { manifest, manifestPath } = loaded;\n\n  const type = opts.type as string;\n  const validTypes = getValidResourceTypes();\n  if (!validTypes.includes(type)) {\n    console.error(`Error: Unknown resource type \"${type}\".`);\n    console.error(`  Valid types: ${validTypes.join(\", \")}`);\n    process.exit(1);\n  }\n  const { entry, isRequired } = buildEntry(type, opts);\n\n  if (isRequired) {\n    manifest.resources.required.push(entry);\n  } else {\n    manifest.resources.optional.push(entry);\n  }\n\n  if (opts.dryRun) {\n    console.log(JSON.stringify(manifest, null, 2));\n    return;\n  }\n\n  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\\n`);\n  console.log(\n    `Added ${entry.alias} as ${isRequired ? \"required\" : \"optional\"} to ${path.relative(cwd, manifestPath)}`,\n  );\n}\n\nasync function runInteractive(opts: AddResourceOptions): Promise<void> {\n  intro(\"Add resource to plugin manifest\");\n\n  const cwd = process.cwd();\n  const pluginDir = path.resolve(cwd, opts.path ?? \".\");\n  const loaded = loadManifest(pluginDir);\n  if (!loaded) return;\n  const { manifest, manifestPath } = loaded;\n\n  const spec = await promptOneResource();\n  if (!spec) {\n    cancel(\"Cancelled.\");\n    process.exit(0);\n  }\n\n  const alias = humanizeResourceType(spec.type);\n  const entry: ResourceRequirement = {\n    type: spec.type as ResourceRequirement[\"type\"],\n    alias,\n    resourceKey: spec.resourceKey,\n    description: spec.description || `Required for ${alias} functionality.`,\n    permission: spec.permission,\n    fields: spec.fields,\n  };\n\n  if (spec.required) {\n    manifest.resources.required.push(entry);\n  } else {\n    manifest.resources.optional.push(entry);\n  }\n\n  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\\n`);\n\n  outro(\"Resource added.\");\n  console.log(\n    `\\nAdded ${alias} as ${spec.required ? \"required\" : \"optional\"} to ${path.relative(cwd, manifestPath)}`,\n  );\n}\n\nasync function runPluginAddResource(opts: AddResourceOptions): Promise<void> {\n  if (opts.type) {\n    runNonInteractive(opts);\n  } else {\n    await runInteractive(opts);\n  }\n}\n\nexport const pluginAddResourceCommand = new Command(\"add-resource\")\n  .description(\n    \"Add a resource requirement to an existing plugin manifest. Overwrites manifest.json in place.\",\n  )\n  .option(\n    \"-p, --path <dir>\",\n    \"Plugin directory containing manifest.json (default: .)\",\n  )\n  .option(\n    \"-t, --type <resource_type>\",\n    \"Resource type (e.g. sql_warehouse, volume). Enables non-interactive mode.\",\n  )\n  .option(\"--required\", \"Mark resource as required (default: true)\", true)\n  .option(\"--no-required\", \"Mark resource as optional\")\n  .option(\"--resource-key <key>\", \"Resource key (default: derived from type)\")\n  .option(\"--description <text>\", \"Description of the resource requirement\")\n  .option(\"--permission <perm>\", \"Permission level (default: from schema)\")\n  .option(\n    \"--fields-json <json>\",\n    'JSON object overriding field env vars (e.g. \\'{\"id\":{\"env\":\"MY_WAREHOUSE_ID\"}}\\')',\n  )\n  .option(\"--dry-run\", \"Preview the updated manifest without writing\")\n  .addHelpText(\n    \"after\",\n    `\nExamples:\n  $ appkit plugin add-resource\n  $ appkit plugin add-resource --path plugins/my-plugin --type sql_warehouse\n  $ appkit plugin add-resource --path plugins/my-plugin --type volume --no-required --dry-run\n  $ appkit plugin add-resource --type sql_warehouse --fields-json '{\"id\":{\"env\":\"MY_WAREHOUSE_ID\"}}'`,\n  )\n  .action((opts) =>\n    runPluginAddResource(opts).catch((err) => {\n      console.error(err);\n      process.exit(1);\n    }),\n  );\n"],"mappings":"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"}

package/dist/cli/commands/plugin/create/create.js

@@ -1,16 +1,150 @@
-import { RESOURCE_TYPE_OPTIONS } from "./resource-defaults.js";
+import { DEFAULT_PERMISSION_BY_TYPE, RESOURCE_TYPE_OPTIONS, getDefaultFieldsForType, getValidResourceTypes, humanizeResourceType, resourceKeyFromType } from "./resource-defaults.js";
 import { promptOneResource } from "./prompt-resource.js";
 import { resolveTargetDir, scaffoldPlugin } from "./scaffold.js";
 import fs from "node:fs";
 import path from "node:path";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import process from "node:process";
 import { cancel, confirm, intro, isCancel, multiselect, outro, select, spinner, text } from "@clack/prompts";
 
 //#region src/cli/commands/plugin/create/create.ts
 const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
 const DEFAULT_VERSION = "0.1.0";
-async function runPluginCreate() {
+const VALID_PLACEMENTS = ["in-repo", "isolated"];
+const REQUIRED_FLAGS = [
+	"placement",
+	"path",
+	"name",
+	"description"
+];
+function deriveDisplayName(name) {
+	return name.split("-").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join(" ");
+}
+function deriveExportName(name) {
+	return name.split("-").map((s, i) => i === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1)).join("");
+}
+function buildResourceFromType(type) {
+	return {
+		type,
+		required: true,
+		description: `Required for ${humanizeResourceType(type)} functionality.`,
+		resourceKey: resourceKeyFromType(type),
+		permission: DEFAULT_PERMISSION_BY_TYPE[type] ?? "CAN_VIEW",
+		fields: getDefaultFieldsForType(type)
+	};
+}
+function parseResourcesJson(json) {
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch {
+		console.error("Error: --resources-json must be valid JSON.");
+		console.error("  Example: --resources-json '[{\"type\":\"sql_warehouse\"}]'");
+		process.exit(1);
+	}
+	if (!Array.isArray(parsed)) {
+		console.error("Error: --resources-json must be a JSON array.");
+		console.error("  Example: --resources-json '[{\"type\":\"sql_warehouse\"}]'");
+		process.exit(1);
+	}
+	return parsed.map((entry, i) => {
+		if (entry == null || typeof entry !== "object") {
+			console.error(`Error: --resources-json entry ${i} is not an object.`);
+			process.exit(1);
+		}
+		if (!entry.type || typeof entry.type !== "string") {
+			console.error(`Error: --resources-json entry ${i} missing required "type" field.`);
+			process.exit(1);
+		}
+		validateResourceType(entry.type);
+		const defaults = buildResourceFromType(entry.type);
+		return {
+			type: entry.type,
+			required: entry.required ?? defaults.required,
+			description: entry.description ?? defaults.description,
+			resourceKey: entry.resourceKey ?? defaults.resourceKey,
+			permission: entry.permission ?? defaults.permission,
+			fields: entry.fields ?? defaults.fields
+		};
+	});
+}
+function validateResourceType(type) {
+	const validTypes = getValidResourceTypes();
+	if (!validTypes.includes(type)) {
+		console.error(`Error: Unknown resource type "${type}".`);
+		console.error(`  Valid types: ${validTypes.join(", ")}`);
+		process.exit(1);
+	}
+}
+function parseResourcesShorthand(csv) {
+	const types = csv.split(",").map((s) => s.trim()).filter(Boolean);
+	for (const t of types) validateResourceType(t);
+	return types.map(buildResourceFromType);
+}
+function printNextSteps(answers, targetDir) {
+	const relativePath = path.relative(process.cwd(), targetDir);
+	const importPath = relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+	const exportName = deriveExportName(answers.name);
+	console.log("\nNext steps:\n");
+	if (answers.placement === "in-repo") {
+		console.log(`  1. Import and register in your server:`);
+		console.log(`     import { ${exportName} } from "${importPath}";`);
+		console.log(`     createApp({ plugins: [ ..., ${exportName}() ] });`);
+		console.log(`  2. Run \`npx appkit plugin sync --write\` to update appkit.plugins.json.\n`);
+	} else {
+		console.log(`  1. cd into the new package and install dependencies:`);
+		console.log(`     cd ${answers.targetPath} && pnpm install`);
+		console.log(`  2. Build: pnpm build`);
+		console.log(`  3. In your app: pnpm add ./${answers.targetPath} @databricks/appkit`);
+		console.log(`  4. Import and register: import { ${exportName} } from "<package-name>";\n`);
+	}
+}
+function runNonInteractive(opts) {
+	const missing = REQUIRED_FLAGS.filter((f) => !opts[f]);
+	if (missing.length > 0) {
+		console.error(`Error: Non-interactive mode requires: ${REQUIRED_FLAGS.map((f) => `--${f}`).join(", ")}`);
+		console.error(`Missing: ${missing.map((f) => `--${f}`).join(", ")}`);
+		console.error("  appkit plugin create --placement in-repo --path plugins/my-plugin --name my-plugin --description \"Does X\"");
+		process.exit(1);
+	}
+	const placement = opts.placement;
+	if (!VALID_PLACEMENTS.includes(placement)) {
+		console.error(`Error: --placement must be one of: ${VALID_PLACEMENTS.join(", ")}`);
+		process.exit(1);
+	}
+	const targetPath = opts.path.trim();
+	if (placement === "in-repo" && (path.isAbsolute(targetPath) || targetPath.startsWith(".."))) {
+		console.error("Error: --path must be a relative path under the current directory for in-repo plugins.");
+		process.exit(1);
+	}
+	const name = opts.name;
+	if (!NAME_PATTERN.test(name)) {
+		console.error("Error: --name must be lowercase, start with a letter, and use only letters, numbers, and hyphens.");
+		process.exit(1);
+	}
+	let resources = [];
+	if (opts.resourcesJson) resources = parseResourcesJson(opts.resourcesJson);
+	else if (opts.resources) resources = parseResourcesShorthand(opts.resources);
+	const answers = {
+		placement,
+		targetPath,
+		name: name.trim(),
+		displayName: opts.displayName?.trim() || deriveDisplayName(name),
+		description: opts.description.trim(),
+		resources,
+		version: DEFAULT_VERSION
+	};
+	const targetDir = resolveTargetDir(process.cwd(), answers);
+	if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0 && !opts.force) {
+		console.error(`Error: Directory ${answers.targetPath} already exists and is not empty.`);
+		console.error("  Use --force to overwrite.");
+		process.exit(1);
+	}
+	scaffoldPlugin(targetDir, answers, { isolated: placement === "isolated" });
+	console.log(`Plugin "${answers.name}" created at ${path.relative(process.cwd(), targetDir)}`);
+	printNextSteps(answers, targetDir);
+}
+async function runInteractive() {
 	intro("Create a new AppKit plugin");
 	try {
 		const placement = await select({
@@ -133,29 +267,39 @@ async function runPluginCreate() {
 			s.stop("Failed.");
 			throw err;
 		}
-		const relativePath = path.relative(process.cwd(), targetDir);
-		const importPath = relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
-		const exportName = answers.name.split("-").map((s, i) => i === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1)).join("");
 		outro("Plugin created successfully.");
-		console.log("\nNext steps:\n");
-		if (placement === "in-repo") {
-			console.log(`  1. Import and register in your server:`);
-			console.log(`     import { ${exportName} } from "${importPath}";`);
-			console.log(`     createApp({ plugins: [ ..., ${exportName}() ] });`);
-			console.log(`  2. Run \`npx appkit plugin sync --write\` to update appkit.plugins.json.\n`);
-		} else {
-			console.log(`  1. cd into the new package and install dependencies:`);
-			console.log(`     cd ${answers.targetPath} && pnpm install`);
-			console.log(`  2. Build: pnpm build`);
-			console.log(`  3. In your app: pnpm add ./${answers.targetPath} @databricks/appkit`);
-			console.log(`  4. Import and register: import { ${exportName} } from "<package-name>";\n`);
-		}
+		printNextSteps(answers, targetDir);
 	} catch (err) {
 		console.error(err);
 		process.exit(1);
 	}
 }
-const pluginCreateCommand = new Command("create").description("Scaffold a new AppKit plugin (interactive)").action(runPluginCreate);
+const OPTIONAL_FLAGS = [
+	"displayName",
+	"resources",
+	"resourcesJson",
+	"force"
+];
+async function runPluginCreate(opts) {
+	if (REQUIRED_FLAGS.some((f) => opts[f] !== void 0)) runNonInteractive(opts);
+	else {
+		if (OPTIONAL_FLAGS.some((f) => opts[f] !== void 0 && opts[f] !== false)) {
+			console.error(`Error: Non-interactive mode requires: ${REQUIRED_FLAGS.map((f) => `--${f}`).join(", ")}`);
+			console.error("  appkit plugin create --placement in-repo --path plugins/my-plugin --name my-plugin --description \"Does X\"");
+			process.exit(1);
+		}
+		await runInteractive();
+	}
+}
+const pluginCreateCommand = new Command("create").description("Scaffold a new AppKit plugin").option("--placement <type>", "Where the plugin lives (in-repo, isolated)").option("--path <dir>", "Target directory for the plugin").option("--name <id>", "Plugin name (lowercase, hyphens allowed)").option("--display-name <name>", "Human-readable display name").option("--description <text>", "Short description of the plugin").addOption(new Option("--resources <types>", "Comma-separated resource types (e.g. sql_warehouse,volume)").conflicts("resourcesJson")).addOption(new Option("--resources-json <json>", "JSON array of resource specs (e.g. '[{\"type\":\"sql_warehouse\"}]')").conflicts("resources")).option("-f, --force", "Overwrite existing directory without confirmation").addHelpText("after", `
+Examples:
+  $ appkit plugin create
+  $ appkit plugin create --placement in-repo --path plugins/my-plugin --name my-plugin --description "Does X"
+  $ appkit plugin create --placement in-repo --path plugins/my-plugin --name my-plugin --description "Does X" --resources sql_warehouse,volume --force
+  $ appkit plugin create --placement isolated --path appkit-plugin-ml --name ml --description "ML" --resources-json '[{"type":"serving_endpoint"}]'`).action((opts) => runPluginCreate(opts).catch((err) => {
+	console.error(err);
+	process.exit(1);
+}));
 
 //#endregion
 export { pluginCreateCommand };