@tagma/sdk 0.3.8 → 0.4.0

package/README.md

@@ -1,11 +1,25 @@
 # @tagma/sdk
 
-A local AI task orchestration SDK for [Bun](https://bun.sh). Define multi-track pipelines in YAML, run AI coding agents (Claude Code, Codex, OpenCode) and shell commands in parallel with dependency resolution, approval gates, and lifecycle hooks.
+> ## ⚠️ Bun-only package — do **not** `npm install`
+>
+> ```bash
+> bun add @tagma/sdk
+> ```
+>
+> This package ships TypeScript source (`main: ./src/sdk.ts`) and relies on
+> Bun's native `.ts` loader. `npm` / `yarn` / `pnpm` installs are blocked by a
+> `preinstall` guard and will fail by design. Get Bun at <https://bun.sh>.
+>
+> *(The `npm i @tagma/sdk` line in the npmjs.com sidebar is auto-generated by
+> the npm registry website and cannot be removed — please ignore it and use
+> the command above.)*
 
-> **Bun ≥ 1.3 required.** `node` + `npm` are not supported — this package ships TypeScript source (`main: ./src/sdk.ts`) and relies on Bun's native `.ts` loader. Install with `bun add`, not `npm install`.
+A local AI task orchestration SDK for [Bun](https://bun.sh). Define multi-track pipelines in YAML, run AI coding agents (Claude Code, Codex, OpenCode) and shell commands in parallel with dependency resolution, approval gates, and lifecycle hooks.
 
 ## Install
 
+**Requires Bun ≥ 1.3.** Node/npm are not supported.
+
 ```bash
 bun add @tagma/sdk
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,13 +15,15 @@
     ".": "./src/sdk.ts"
   },
   "files": [
-    "src"
+    "src",
+    "scripts/preinstall.js"
   ],
   "engines": {
     "bun": ">=1.3"
   },
   "packageManager": "bun@1.3.7",
   "scripts": {
+    "preinstall": "node scripts/preinstall.js",
     "test": "bun test",
     "release": "bun scripts/release.ts",
     "release:publish": "bun scripts/release.ts --publish"

package/scripts/preinstall.js

@@ -0,0 +1,38 @@
+// Preinstall guard — refuses installation under npm / yarn / pnpm.
+// @tagma/sdk ships TypeScript source (main: ./src/sdk.ts) and relies on
+// Bun's native .ts loader, so installing under Node-based managers leaves
+// users with a broken package.
+//
+// Bun detection: we can't rely on process.versions.bun alone, because bun
+// invokes lifecycle scripts via the interpreter named in the script command
+// ("node scripts/preinstall.js" runs under node even when called from bun
+// install). Bun does, however, set npm_config_user_agent to a string that
+// starts with "bun/<version> ...", which is the canonical cross-manager
+// signal. Check both for safety.
+
+const ua = process.env.npm_config_user_agent || '';
+if (process.versions.bun || ua.startsWith('bun/') || ua.startsWith('bun ')) {
+  process.exit(0);
+}
+
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+
+process.stderr.write(
+  [
+    '',
+    red(bold('  @tagma/sdk requires Bun (>= 1.3).')),
+    '',
+    '  This package ships TypeScript source and uses Bun\'s native .ts loader.',
+    '  npm / yarn / pnpm cannot consume it.',
+    '',
+    '  Install with:',
+    cyan('    bun add @tagma/sdk'),
+    '',
+    '  Get Bun: https://bun.sh',
+    '',
+  ].join('\n') + '\n',
+);
+
+process.exit(1);

package/src/schema.ts

@@ -41,14 +41,16 @@ function validateRawTask(task: RawTaskConfig, trackId: string): void {
   if (!task.id) throw new Error(`track "${trackId}": task.id is required`);
   if (task.use) return; // template usage, validated later
 
-  const hasPrompt = typeof task.prompt === 'string' && task.prompt.length > 0;
-  const hasCommand = typeof task.command === 'string' && task.command.length > 0;
-  if (!hasPrompt && !hasCommand) {
+  const hasPromptKey = typeof task.prompt === 'string';
+  const hasCommandKey = typeof task.command === 'string';
+  if (!hasPromptKey && !hasCommandKey) {
     throw new Error(`task "${task.id}": must have either "prompt" or "command"`);
   }
-  if (hasPrompt && hasCommand) {
+  if (hasPromptKey && hasCommandKey) {
     throw new Error(`task "${task.id}": cannot have both "prompt" and "command"`);
   }
+  // Empty-content tasks (e.g. `prompt: ''`) are allowed at parse time and
+  // flagged as non-fatal validation errors by validate-raw.ts.
 }
 
 // ═══ Template Expansion ═══

package/src/validate-raw.ts

@@ -111,19 +111,30 @@ export function validateRaw(config: RawPipelineConfig): ValidationError[] {
       // Template-based tasks: skip prompt/command checks (params validated at runtime)
       if (task.use) continue;
 
-      const hasPrompt = typeof task.prompt === 'string' && task.prompt.trim().length > 0;
-      const hasCommand = typeof task.command === 'string' && task.command.trim().length > 0;
+      const hasPromptKey = typeof task.prompt === 'string';
+      const hasCommandKey = typeof task.command === 'string';
+      const promptEmpty = hasPromptKey && task.prompt!.trim().length === 0;
+      const commandEmpty = hasCommandKey && task.command!.trim().length === 0;
 
-      if (!hasPrompt && !hasCommand) {
+      if (hasPromptKey && hasCommandKey) {
+        errors.push({
+          path: taskPath,
+          message: `Task "${task.id}": cannot have both "prompt" and "command"`,
+        });
+      } else if (!hasPromptKey && !hasCommandKey) {
         errors.push({
           path: taskPath,
           message: `Task "${task.id}": must have "prompt" or "command"`,
         });
-      }
-      if (hasPrompt && hasCommand) {
+      } else if (promptEmpty) {
         errors.push({
           path: taskPath,
-          message: `Task "${task.id}": cannot have both "prompt" and "command"`,
+          message: `Task "${task.id}": prompt content cannot be empty`,
+        });
+      } else if (commandEmpty) {
+        errors.push({
+          path: taskPath,
+          message: `Task "${task.id}": command content cannot be empty`,
         });
       }