@crewx/shared 0.0.6-rc.21 → 0.0.6-rc.23

package/crewx-api-credential.d.ts

@@ -0,0 +1,14 @@
+export type RuntimeCredentialPurpose = 'notify' | 'wi' | 'chromex-negotiate' | 'pairing';
+export interface ResolvedCredential {
+    token: string;
+    source: 'env' | 'file';
+}
+type CrewxCredentialErrorCode = 'MISSING' | 'BAD_MODE' | 'UNREADABLE';
+export declare class CrewxCredentialError extends Error {
+    readonly code: CrewxCredentialErrorCode;
+    readonly exitCode: number;
+    constructor(code: CrewxCredentialErrorCode, message: string);
+}
+export declare function resolveCrewxApiCredential(purpose: RuntimeCredentialPurpose, env?: NodeJS.ProcessEnv): ResolvedCredential;
+export declare function authorizationHeader(cred: ResolvedCredential): Record<'Authorization', string>;
+export {};

package/crewx-api-credential.js

@@ -0,0 +1,135 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrewxCredentialError = void 0;
+exports.resolveCrewxApiCredential = resolveCrewxApiCredential;
+exports.authorizationHeader = authorizationHeader;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const sdk_1 = require("@crewx/sdk");
+const RUNTIME_CREDENTIAL_PURPOSES = new Set([
+    'notify',
+    'wi',
+    'chromex-negotiate',
+    'pairing',
+]);
+// These are sysexits-style values so shell callers can distinguish the local
+// credential failure before an HTTP request is attempted.
+const EXIT_CODES = {
+    MISSING: 78,
+    BAD_MODE: 77,
+    UNREADABLE: 74,
+};
+const HEX_64 = '[0-9a-f]{64}';
+class CrewxCredentialError extends Error {
+    code;
+    exitCode;
+    constructor(code, message) {
+        super(message);
+        this.name = 'CrewxCredentialError';
+        this.code = code;
+        this.exitCode = EXIT_CODES[code];
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.CrewxCredentialError = CrewxCredentialError;
+function isErrnoCode(error, code) {
+    return typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === code;
+}
+function credentialPath(purpose) {
+    return path.join((0, sdk_1.getCrewxHome)(), 'auth', 'runtime', `${purpose}.token`);
+}
+function invalidPurpose(purpose) {
+    throw new TypeError(`Unsupported runtime credential purpose: ${String(purpose)}`);
+}
+function missingCredential(purpose, filePath) {
+    throw new CrewxCredentialError('MISSING', `Runtime credential '${purpose}' is missing at ${filePath}. `
+        + 'Run the CrewX server once to create it or set CREWX_API_TOKEN.');
+}
+function badMode(purpose, filePath) {
+    throw new CrewxCredentialError('BAD_MODE', `Runtime credential '${purpose}' at ${filePath} has insecure permissions; expected mode 0600.`);
+}
+function unreadableCredential(purpose, filePath) {
+    throw new CrewxCredentialError('UNREADABLE', `Runtime credential '${purpose}' at ${filePath} is unreadable or invalid. `
+        + 'Check the file contents and permissions.');
+}
+function readRuntimeCredential(purpose) {
+    const filePath = credentialPath(purpose);
+    let stats;
+    try {
+        // lstat prevents a symlink from bypassing the mode check on POSIX.
+        stats = fs.lstatSync(filePath);
+    }
+    catch (error) {
+        if (isErrnoCode(error, 'ENOENT'))
+            missingCredential(purpose, filePath);
+        unreadableCredential(purpose, filePath);
+    }
+    if (!stats.isFile())
+        unreadableCredential(purpose, filePath);
+    // Windows does not expose POSIX mode semantics; the server contract skips
+    // this check there as well.
+    if (process.platform !== 'win32' && (stats.mode & 0o777) !== 0o600) {
+        badMode(purpose, filePath);
+    }
+    let token;
+    try {
+        token = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isErrnoCode(error, 'ENOENT'))
+            missingCredential(purpose, filePath);
+        unreadableCredential(purpose, filePath);
+    }
+    const expected = new RegExp(`^crewxrt_${purpose}_${HEX_64}$`);
+    if (!expected.test(token))
+        unreadableCredential(purpose, filePath);
+    return token;
+}
+function resolveCrewxApiCredential(purpose, env = process.env) {
+    if (!RUNTIME_CREDENTIAL_PURPOSES.has(purpose))
+        invalidPurpose(purpose);
+    const envToken = env['CREWX_API_TOKEN'];
+    if (typeof envToken === 'string' && envToken.length > 0) {
+        return { token: envToken, source: 'env' };
+    }
+    return { token: readRuntimeCredential(purpose), source: 'file' };
+}
+function authorizationHeader(cred) {
+    return { Authorization: `Bearer ${cred.token}` };
+}

package/crewx-api-credential.ts

@@ -0,0 +1,131 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getCrewxHome } from '@crewx/sdk';
+
+export type RuntimeCredentialPurpose = 'notify' | 'wi' | 'chromex-negotiate' | 'pairing';
+
+export interface ResolvedCredential {
+  token: string;
+  source: 'env' | 'file';
+}
+
+type CrewxCredentialErrorCode = 'MISSING' | 'BAD_MODE' | 'UNREADABLE';
+
+const RUNTIME_CREDENTIAL_PURPOSES = new Set<RuntimeCredentialPurpose>([
+  'notify',
+  'wi',
+  'chromex-negotiate',
+  'pairing',
+]);
+
+// These are sysexits-style values so shell callers can distinguish the local
+// credential failure before an HTTP request is attempted.
+const EXIT_CODES: Record<CrewxCredentialErrorCode, number> = {
+  MISSING: 78,
+  BAD_MODE: 77,
+  UNREADABLE: 74,
+};
+
+const HEX_64 = '[0-9a-f]{64}';
+
+export class CrewxCredentialError extends Error {
+  readonly code: CrewxCredentialErrorCode;
+  readonly exitCode: number;
+
+  constructor(code: CrewxCredentialErrorCode, message: string) {
+    super(message);
+    this.name = 'CrewxCredentialError';
+    this.code = code;
+    this.exitCode = EXIT_CODES[code];
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+function isErrnoCode(error: unknown, code: string): boolean {
+  return typeof error === 'object'
+    && error !== null
+    && 'code' in error
+    && (error as { code?: unknown }).code === code;
+}
+
+function credentialPath(purpose: RuntimeCredentialPurpose): string {
+  return path.join(getCrewxHome(), 'auth', 'runtime', `${purpose}.token`);
+}
+
+function invalidPurpose(purpose: RuntimeCredentialPurpose): never {
+  throw new TypeError(`Unsupported runtime credential purpose: ${String(purpose)}`);
+}
+
+function missingCredential(purpose: RuntimeCredentialPurpose, filePath: string): never {
+  throw new CrewxCredentialError(
+    'MISSING',
+    `Runtime credential '${purpose}' is missing at ${filePath}. `
+      + 'Run the CrewX server once to create it or set CREWX_API_TOKEN.',
+  );
+}
+
+function badMode(purpose: RuntimeCredentialPurpose, filePath: string): never {
+  throw new CrewxCredentialError(
+    'BAD_MODE',
+    `Runtime credential '${purpose}' at ${filePath} has insecure permissions; expected mode 0600.`,
+  );
+}
+
+function unreadableCredential(purpose: RuntimeCredentialPurpose, filePath: string): never {
+  throw new CrewxCredentialError(
+    'UNREADABLE',
+    `Runtime credential '${purpose}' at ${filePath} is unreadable or invalid. `
+      + 'Check the file contents and permissions.',
+  );
+}
+
+function readRuntimeCredential(purpose: RuntimeCredentialPurpose): string {
+  const filePath = credentialPath(purpose);
+  let stats: fs.Stats;
+
+  try {
+    // lstat prevents a symlink from bypassing the mode check on POSIX.
+    stats = fs.lstatSync(filePath);
+  } catch (error: unknown) {
+    if (isErrnoCode(error, 'ENOENT')) missingCredential(purpose, filePath);
+    unreadableCredential(purpose, filePath);
+  }
+
+  if (!stats!.isFile()) unreadableCredential(purpose, filePath);
+
+  // Windows does not expose POSIX mode semantics; the server contract skips
+  // this check there as well.
+  if (process.platform !== 'win32' && (stats!.mode & 0o777) !== 0o600) {
+    badMode(purpose, filePath);
+  }
+
+  let token: string;
+  try {
+    token = fs.readFileSync(filePath, 'utf8');
+  } catch (error: unknown) {
+    if (isErrnoCode(error, 'ENOENT')) missingCredential(purpose, filePath);
+    unreadableCredential(purpose, filePath);
+  }
+
+  const expected = new RegExp(`^crewxrt_${purpose}_${HEX_64}$`);
+  if (!expected.test(token!)) unreadableCredential(purpose, filePath);
+  return token!;
+}
+
+export function resolveCrewxApiCredential(
+  purpose: RuntimeCredentialPurpose,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedCredential {
+  if (!RUNTIME_CREDENTIAL_PURPOSES.has(purpose)) invalidPurpose(purpose);
+
+  const envToken = env['CREWX_API_TOKEN'];
+  if (typeof envToken === 'string' && envToken.length > 0) {
+    return { token: envToken, source: 'env' };
+  }
+
+  return { token: readRuntimeCredential(purpose), source: 'file' };
+}
+
+export function authorizationHeader(cred: ResolvedCredential): Record<'Authorization', string> {
+  return { Authorization: `Bearer ${cred.token}` };
+}

package/package.json

@@ -1,12 +1,41 @@
 {
   "name": "@crewx/shared",
-  "version": "0.0.6-rc.21",
+  "version": "0.0.6-rc.23",
   "main": "skill-tracer.js",
+  "exports": {
+    ".": {
+      "types": "./skill-tracer.d.ts",
+      "require": "./skill-tracer.js",
+      "default": "./skill-tracer.js"
+    },
+    "./skill-tracer": {
+      "types": "./skill-tracer.d.ts",
+      "require": "./skill-tracer.js",
+      "default": "./skill-tracer.js"
+    },
+    "./crewx-api-credential": {
+      "types": "./crewx-api-credential.d.ts",
+      "require": "./crewx-api-credential.js",
+      "default": "./crewx-api-credential.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "crewx-api-credential": [
+        "crewx-api-credential.d.ts"
+      ]
+    }
+  },
   "description": "Shared utilities for CrewX built-in packages",
   "dependencies": {
-    "@crewx/sdk": "0.8.9-rc.34"
+    "@crewx/sdk": "0.9.0-rc.108"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.json",
     "test": "echo no tests"
   }
 }

package/skill-tracer.js

@@ -24,9 +24,7 @@ const { generateId } = require('@crewx/sdk');
  * crewx.db 경로 찾기
  */
 function getDbPath() {
-  if (process.env.CREWX_TRACES_DB || process.env.CREWX_DB) {
-    return process.env.CREWX_TRACES_DB || process.env.CREWX_DB;
-  }
+  if (process.env.CREWX_DB) return process.env.CREWX_DB;
 
   return path.join(os.homedir(), '.crewx', 'crewx.db');
 }
@@ -35,141 +33,67 @@ function getDbPath() {
 const getTracesDbPath = getDbPath;
 
 /**
- * crewx.db 연결 및 테이블 확인
- * Returns null if better-sqlite3 is unavailable or DB cannot be opened.
+ * Open an already initialized crewx.db for trace writes.
+ * This function never creates a database, directory, or schema.
+ * Returns null if better-sqlite3 is unavailable, the database is missing, or
+ * the existing file does not contain the tracing tables used by this module.
  */
 function getDb() {
   if (!Database) return null;
 
   const dbPath = getDbPath();
-  const dir = path.dirname(dbPath);
-
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
+  if (!fs.existsSync(dbPath)) return null;
 
-  const db = new Database(dbPath);
-  db.exec('PRAGMA journal_mode = WAL');
-  db.exec('PRAGMA busy_timeout = 5000');
-  db.exec('PRAGMA foreign_keys = ON');
-
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS tasks (
-      id TEXT PRIMARY KEY,
-      agent_id TEXT NOT NULL,
-      user_id TEXT,
-      prompt TEXT NOT NULL,
-      mode TEXT NOT NULL DEFAULT 'execute',
-      status TEXT NOT NULL DEFAULT 'running',
-      result TEXT,
-      error TEXT,
-      started_at TEXT NOT NULL,
-      completed_at TEXT,
-      duration_ms INTEGER,
-      metadata TEXT,
-      project_id TEXT,
-      project_name TEXT
-    )
-  `);
-
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS spans (
-      id TEXT PRIMARY KEY,
-      task_id TEXT,
-      parent_span_id TEXT,
-      name TEXT NOT NULL,
-      kind TEXT NOT NULL DEFAULT 'internal',
-      status TEXT NOT NULL DEFAULT 'ok',
-      started_at TEXT NOT NULL,
-      completed_at TEXT,
-      duration_ms INTEGER,
-      input TEXT,
-      output TEXT,
-      error TEXT,
-      attributes TEXT,
-      FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE SET NULL,
-      FOREIGN KEY (parent_span_id) REFERENCES spans(id) ON DELETE SET NULL
-    )
-  `);
-
-  ensureProjectColumns(db);
-  ensureSpansTaskIdNullable(db);
-
-  return db;
-}
-
-function ensureProjectColumns(db) {
+  let db;
   try {
-    const columns = db.prepare('PRAGMA table_info(tasks)').all().map((col) => col.name);
-    if (!columns.includes('project_id')) {
-      db.exec(`ALTER TABLE tasks ADD COLUMN project_id TEXT`);
-    }
-    if (!columns.includes('project_name')) {
-      db.exec(`ALTER TABLE tasks ADD COLUMN project_name TEXT`);
-    }
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_tasks_project_id ON tasks(project_id)`);
-  } catch {
-    // Best-effort; ignore failures
-  }
-}
+    db = new Database(dbPath, { fileMustExist: true });
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA busy_timeout = 5000');
+    db.exec('PRAGMA foreign_keys = ON');
 
-function ensureSpansTaskIdNullable(db) {
-  try {
-    const columns = db.prepare('PRAGMA table_info(spans)').all();
-    const taskIdColumn = columns.find((col) => col.name === 'task_id');
-    if (!taskIdColumn || taskIdColumn.notnull === 0) {
-      return;
+    if (!hasTraceSchema(db)) {
+      db.close();
+      return null;
     }
 
-    db.exec('PRAGMA foreign_keys = OFF');
-    db.exec('BEGIN');
-    db.exec(`
-      CREATE TABLE spans_backup (
-        id TEXT PRIMARY KEY,
-        task_id TEXT,
-        parent_span_id TEXT,
-        name TEXT NOT NULL,
-        kind TEXT NOT NULL DEFAULT 'internal',
-        status TEXT NOT NULL DEFAULT 'ok',
-        started_at TEXT NOT NULL,
-        completed_at TEXT,
-        duration_ms INTEGER,
-        input TEXT,
-        output TEXT,
-        error TEXT,
-        attributes TEXT,
-        FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE SET NULL,
-        FOREIGN KEY (parent_span_id) REFERENCES spans_backup(id) ON DELETE SET NULL
-      )
-    `);
-    db.exec(`
-      INSERT INTO spans_backup (
-        id, task_id, parent_span_id, name, kind, status, started_at,
-        completed_at, duration_ms, input, output, error, attributes
-      )
-      SELECT
-        id, task_id, parent_span_id, name, kind, status, started_at,
-        completed_at, duration_ms, input, output, error, attributes
-      FROM spans
-    `);
-    db.exec('DROP TABLE spans');
-    db.exec('ALTER TABLE spans_backup RENAME TO spans');
-    db.exec('COMMIT');
-    db.exec('PRAGMA foreign_keys = ON');
-  } catch {
+    return db;
+  } catch (error) {
     try {
-      db.exec('ROLLBACK');
+      db?.close();
     } catch {
-      // Best-effort rollback
-    }
-    try {
-      db.exec('PRAGMA foreign_keys = ON');
-    } catch {
-      // Best-effort; ignore failures
+      // Best-effort cleanup after an open or pragma failure.
     }
+    throw error;
   }
 }
 
+function hasTraceSchema(db) {
+  const requiredColumns = {
+    tasks: ['id'],
+    spans: [
+      'id',
+      'task_id',
+      'name',
+      'kind',
+      'status',
+      'started_at',
+      'completed_at',
+      'duration_ms',
+      'input',
+      'output',
+      'error',
+      'attributes',
+    ],
+  };
+
+  return Object.entries(requiredColumns).every(([tableName, columns]) => {
+    const availableColumns = new Set(
+      db.prepare(`PRAGMA table_info(${tableName})`).all().map((column) => column.name),
+    );
+    return columns.every((column) => availableColumns.has(column));
+  });
+}
+
 function resolveProjectContext() {
   const projectPath = path.resolve(process.cwd());
   return {

package/tests/crewx-api-credential.test.ts

@@ -0,0 +1,110 @@
+// @vitest-environment node
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  authorizationHeader,
+  CrewxCredentialError,
+  resolveCrewxApiCredential,
+} from '../crewx-api-credential';
+
+const VALID_HEX = 'a'.repeat(64);
+
+let tmpHome: string;
+const savedEnv = { ...process.env };
+
+function runtimePath(purpose: string): string {
+  return path.join(tmpHome, 'auth', 'runtime', `${purpose}.token`);
+}
+
+function writeCredential(purpose: string, mode = 0o600, token = `crewxrt_${purpose}_${VALID_HEX}`): void {
+  const file = runtimePath(purpose);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, token, { encoding: 'utf8', mode });
+  fs.chmodSync(file, mode);
+}
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'crewx-runtime-credential-'));
+  process.env['CREWX_HOME'] = tmpHome;
+  delete process.env['CREWX_API_TOKEN'];
+});
+
+afterEach(() => {
+  process.env = { ...savedEnv };
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+describe('resolveCrewxApiCredential', () => {
+  it('resolves a purpose-scoped 0600 runtime credential and builds its Bearer header', () => {
+    writeCredential('notify');
+
+    const credential = resolveCrewxApiCredential('notify');
+
+    expect(credential).toEqual({ token: `crewxrt_notify_${VALID_HEX}`, source: 'file' });
+    expect(authorizationHeader(credential)).toEqual({
+      Authorization: `Bearer crewxrt_notify_${VALID_HEX}`,
+    });
+  });
+
+  it('resolves the pairing runtime credential', () => {
+    writeCredential('pairing');
+
+    expect(resolveCrewxApiCredential('pairing')).toEqual({
+      token: `crewxrt_pairing_${VALID_HEX}`,
+      source: 'file',
+    });
+  });
+
+  it('prefers CREWX_API_TOKEN without inspecting the runtime credential file', () => {
+    writeCredential('wi', 0o644);
+    process.env['CREWX_API_TOKEN'] = 'env-token';
+
+    expect(resolveCrewxApiCredential('wi')).toEqual({ token: 'env-token', source: 'env' });
+  });
+
+  it('fails with MISSING and a non-zero exit code when the runtime file is absent', () => {
+    expect(() => resolveCrewxApiCredential('notify')).toThrow(CrewxCredentialError);
+
+    try {
+      resolveCrewxApiCredential('notify');
+      throw new Error('expected resolveCrewxApiCredential to throw');
+    } catch (error) {
+      expect(error).toMatchObject({ code: 'MISSING', exitCode: expect.any(Number) });
+      expect((error as Error).message).toContain('notify.token');
+      expect((error as CrewxCredentialError).exitCode).toBe(78);
+    }
+  });
+
+  it('fails with a distinct BAD_MODE error when the runtime file is not 0600', () => {
+    writeCredential('notify', 0o644);
+
+    expect(() => resolveCrewxApiCredential('notify')).toThrow(CrewxCredentialError);
+
+    try {
+      resolveCrewxApiCredential('notify');
+      throw new Error('expected resolveCrewxApiCredential to throw');
+    } catch (error) {
+      expect(error).toMatchObject({ code: 'BAD_MODE', exitCode: expect.any(Number) });
+      expect((error as Error).message).toContain('0600');
+      expect((error as CrewxCredentialError).exitCode).toBe(77);
+    }
+  });
+
+  it('fails with UNREADABLE when the file content does not match the purpose contract', () => {
+    writeCredential('chromex-negotiate', 0o600, 'not-a-runtime-token');
+
+    expect(() => resolveCrewxApiCredential('chromex-negotiate')).toThrow(CrewxCredentialError);
+
+    try {
+      resolveCrewxApiCredential('chromex-negotiate');
+      throw new Error('expected resolveCrewxApiCredential to throw');
+    } catch (error) {
+      expect(error).toMatchObject({ code: 'UNREADABLE', exitCode: expect.any(Number) });
+      expect((error as CrewxCredentialError).exitCode).toBe(74);
+      expect((error as Error).message).not.toContain('not-a-runtime-token');
+    }
+  });
+});

package/tests/skill-tracer.test.ts

@@ -6,6 +6,36 @@ import Database from 'better-sqlite3';
 
 const SPAN_ID_PATTERN = /^spn_[A-Za-z0-9]{8}$/;
 
+function createTracerDb(dbPath: string): void {
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+  db.exec(`
+    CREATE TABLE tasks (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT,
+      prompt TEXT,
+      status TEXT,
+      started_at TEXT
+    );
+    CREATE TABLE spans (
+      id TEXT PRIMARY KEY,
+      task_id TEXT,
+      parent_span_id TEXT,
+      name TEXT NOT NULL,
+      kind TEXT NOT NULL DEFAULT 'internal',
+      status TEXT NOT NULL DEFAULT 'ok',
+      started_at TEXT NOT NULL,
+      completed_at TEXT,
+      duration_ms INTEGER,
+      input TEXT,
+      output TEXT,
+      error TEXT,
+      attributes TEXT
+    );
+  `);
+  db.close();
+}
+
 describe('shared/skill-tracer', () => {
   const sharedDir = path.resolve(__dirname, '..');
 
@@ -48,6 +78,7 @@ describe('shared/skill-tracer', () => {
 
     process.env.CREWX_DB = dbPath;
     delete process.env.CREWX_TASK_ID;
+    createTracerDb(dbPath);
 
     try {
       const trace = tracer.trace('memory', 'index core_sqa');
@@ -69,6 +100,39 @@ describe('shared/skill-tracer', () => {
       fs.rmSync(tempDir, { recursive: true, force: true });
     }
   });
+
+  it('does not create a missing target database and no-ops without throwing', () => {
+    const tracer = require(path.join(sharedDir, 'skill-tracer.js'));
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-tracer-missing-'));
+    const dbPath = path.join(tempDir, 'nested', 'crewx.db');
+    const previousDbPath = process.env.CREWX_DB;
+    const previousTaskId = process.env.CREWX_TASK_ID;
+
+    process.env.CREWX_DB = dbPath;
+    delete process.env.CREWX_TASK_ID;
+
+    try {
+      expect(() => {
+        const trace = tracer.trace('memory', 'index core_sqa');
+        expect(trace._skipped).toBe(true);
+        trace.ok('ignored');
+      }).not.toThrow();
+      expect(fs.existsSync(dbPath)).toBe(false);
+      expect(fs.existsSync(path.dirname(dbPath))).toBe(false);
+    } finally {
+      if (previousDbPath === undefined) {
+        delete process.env.CREWX_DB;
+      } else {
+        process.env.CREWX_DB = previousDbPath;
+      }
+      if (previousTaskId === undefined) {
+        delete process.env.CREWX_TASK_ID;
+      } else {
+        process.env.CREWX_TASK_ID = previousTaskId;
+      }
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe('shared/skill-tracer output capture', () => {
@@ -85,6 +149,7 @@ describe('shared/skill-tracer output capture', () => {
     prevTaskId = process.env.CREWX_TASK_ID;
     process.env.CREWX_DB = dbPath;
     delete process.env.CREWX_TASK_ID;
+    createTracerDb(dbPath);
   });
 
   afterEach(() => {

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "rootDir": ".",
+    "outDir": ".",
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": false,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["crewx-api-credential.ts"],
+  "exclude": ["node_modules", "tests"]
+}