@tagma/sdk 0.3.7 → 0.3.9

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.7",
+  "version": "0.3.9",
   "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/registry.ts

@@ -1,6 +1,6 @@
 import type {
   PluginCategory, DriverPlugin, TriggerPlugin,
-  CompletionPlugin, MiddlewarePlugin,
+  CompletionPlugin, MiddlewarePlugin, PluginManifest,
 } from './types';
 
 type PluginType = DriverPlugin | TriggerPlugin | CompletionPlugin | MiddlewarePlugin;
@@ -155,6 +155,41 @@ export function isValidPluginName(name: unknown): name is string {
   return typeof name === 'string' && PLUGIN_NAME_RE.test(name);
 }
 
+/**
+ * Parse and validate the `tagmaPlugin` field of a `package.json` blob.
+ *
+ * Returns the strongly-typed manifest if the field is present and
+ * well-formed (`category` is one of the four known categories and `type`
+ * is a non-empty string). Returns `null` if the field is absent — that
+ * is the host's signal that the package is a library, not a plugin.
+ *
+ * Throws if the field is present but malformed: that's a packaging bug
+ * the plugin author should hear about loudly, not a silent skip.
+ *
+ * Hosts use this during auto-discovery to decide whether to load a
+ * package as a plugin without having to dynamically `import()` it.
+ */
+export function readPluginManifest(pkgJson: unknown): PluginManifest | null {
+  if (!pkgJson || typeof pkgJson !== 'object') return null;
+  const raw = (pkgJson as Record<string, unknown>).tagmaPlugin;
+  if (raw === undefined) return null;
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('tagmaPlugin field must be an object with { category, type }');
+  }
+  const m = raw as Record<string, unknown>;
+  const category = m.category;
+  const type = m.type;
+  if (typeof category !== 'string' || !VALID_CATEGORIES.has(category as PluginCategory)) {
+    throw new Error(
+      `tagmaPlugin.category must be one of ${[...VALID_CATEGORIES].join(', ')}, got ${JSON.stringify(category)}`
+    );
+  }
+  if (typeof type !== 'string' || type.length === 0) {
+    throw new Error(`tagmaPlugin.type must be a non-empty string, got ${JSON.stringify(type)}`);
+  }
+  return { category: category as PluginCategory, type };
+}
+
 export async function loadPlugins(pluginNames: readonly string[]): Promise<void> {
   for (const name of pluginNames) {
     if (!isValidPluginName(name)) {

package/src/sdk.ts

@@ -51,6 +51,7 @@ export {
   listRegistered,
   isValidPluginName,
   PLUGIN_NAME_RE,
+  readPluginManifest,
 } from './registry';
 export type { RegisterResult } from './registry';