grada-run 0.0.2 → 0.32.0

package/tests/aws.test.js

@@ -0,0 +1,244 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { provisionStateBucket, handleAwsAuthError, isAuthError, handleAuthErrorBranch, resolveClient, hasAwsCli, resetAwsCliCache } from '../src/utils/aws.js';
+
+const { mockSpawnSync } = vi.hoisted(() => ({ mockSpawnSync: vi.fn() }));
+
+vi.mock('child_process', () => ({
+  spawnSync: mockSpawnSync,
+}));
+
+const {
+  mockS3Send,
+  mockStsSend,
+  MockS3Client,
+  MockSTSClient,
+  MockGetCallerIdentityCommand,
+  MockCreateBucketCommand,
+  MockPutBucketVersioningCommand,
+  MockPutBucketTaggingCommand,
+} = vi.hoisted(() => {
+  const s3Send = vi.fn();
+  const stsSend = vi.fn();
+  const mockCommand = (input) => Object.assign({}, input);
+  return {
+    mockS3Send: s3Send,
+    mockStsSend: stsSend,
+    MockS3Client: vi.fn(function () {
+      this.send = s3Send;
+    }),
+    MockSTSClient: vi.fn(function () {
+      this.send = stsSend;
+    }),
+    MockGetCallerIdentityCommand: vi.fn(function (input) {
+      Object.assign(this, mockCommand(input));
+    }),
+    MockCreateBucketCommand: vi.fn(function (input) {
+      Object.assign(this, mockCommand(input));
+    }),
+    MockPutBucketVersioningCommand: vi.fn(function (input) {
+      Object.assign(this, mockCommand(input));
+    }),
+    MockPutBucketTaggingCommand: vi.fn(function (input) {
+      Object.assign(this, mockCommand(input));
+    }),
+  };
+});
+
+vi.mock('@aws-sdk/client-s3', () => {
+  return {
+    S3Client: MockS3Client,
+    CreateBucketCommand: MockCreateBucketCommand,
+    PutBucketVersioningCommand: MockPutBucketVersioningCommand,
+    PutBucketTaggingCommand: MockPutBucketTaggingCommand,
+  };
+});
+
+vi.mock('@aws-sdk/client-sts', () => {
+  return {
+    STSClient: MockSTSClient,
+    GetCallerIdentityCommand: MockGetCallerIdentityCommand,
+  };
+});
+
+describe('provisionStateBucket', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockS3Send.mockReset().mockResolvedValue({});
+    mockStsSend.mockReset().mockResolvedValue({ Account: '123456789012' });
+  });
+
+  it("when region is 'us-east-1', CreateBucketConfiguration is undefined", async () => {
+    await provisionStateBucket('us-east-1', 'my-project');
+
+    expect(MockCreateBucketCommand).toHaveBeenCalledWith(
+      expect.objectContaining({ CreateBucketConfiguration: undefined }),
+    );
+    expect(MockCreateBucketCommand.mock.calls[0][0].CreateBucketConfiguration).toBeUndefined();
+  });
+
+  it("when region is 'us-east-2', CreateBucketConfiguration has LocationConstraint 'us-east-2'", async () => {
+    await provisionStateBucket('us-east-2', 'my-project');
+
+    expect(MockCreateBucketCommand).toHaveBeenCalledWith(
+      expect.objectContaining({
+        CreateBucketConfiguration: { LocationConstraint: 'us-east-2' },
+      }),
+    );
+    expect(MockCreateBucketCommand.mock.calls[0][0].CreateBucketConfiguration).toEqual({
+      LocationConstraint: 'us-east-2',
+    });
+  });
+});
+
+describe('handleAwsAuthError', () => {
+  let exitSpy;
+  let consoleSpy;
+
+  beforeEach(() => {
+    exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {});
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    exitSpy.mockRestore();
+    consoleSpy.mockRestore();
+  });
+
+  it('stops the spinner, prints install guidance, and exits 1 when the AWS CLI is missing', () => {
+    const spinner = { stop: vi.fn() };
+
+    handleAwsAuthError({ name: 'ExpiredTokenException' }, spinner, {
+      spawnSyncImpl: () => {
+        throw new Error('ENOENT');
+      },
+    });
+
+    expect(spinner.stop).toHaveBeenCalledWith(expect.stringContaining('AWS session expired'));
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('AWS CLI not found'));
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('aws-credentials.md'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it('prints sso login guidance when the AWS CLI is present', () => {
+    const spinner = { stop: vi.fn() };
+
+    handleAwsAuthError({ name: 'UnrecognizedClientException' }, spinner, {
+      spawnSyncImpl: () => ({ status: 0 }),
+    });
+
+    expect(spinner.stop).toHaveBeenCalledWith(expect.stringContaining('AWS session expired'));
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('aws sso login'));
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('aws-credentials.md'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it('tolerates a null spinner', () => {
+    expect(() =>
+      handleAwsAuthError({ name: 'ExpiredTokenException' }, null, {
+        spawnSyncImpl: () => ({ status: 0 }),
+      }),
+    ).not.toThrow();
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('aws sso login'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});
+
+describe('isAuthError', () => {
+  it('matches expired/invalid credential errors only', () => {
+    expect(isAuthError({ name: 'ExpiredTokenException' })).toBe(true);
+    expect(isAuthError({ name: 'UnrecognizedClientException' })).toBe(true);
+    expect(isAuthError({ name: 'ResourceNotFoundException' })).toBe(false);
+    expect(isAuthError({})).toBe(false);
+    expect(isAuthError(null)).toBe(false);
+    expect(isAuthError(undefined)).toBe(false);
+  });
+});
+
+describe('handleAuthErrorBranch', () => {
+  let exitSpy;
+  let consoleSpy;
+
+  beforeEach(() => {
+    exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {});
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    exitSpy.mockRestore();
+    consoleSpy.mockRestore();
+  });
+
+  it('handles auth errors and reports true', () => {
+    const handled = handleAuthErrorBranch({ name: 'ExpiredTokenException' }, null, {
+      spawnSyncImpl: () => ({ status: 0 }),
+    });
+
+    expect(handled).toBe(true);
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('aws sso login'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it('ignores non-auth errors and reports false without exiting', () => {
+    const handled = handleAuthErrorBranch({ name: 'ResourceNotFoundException', message: 'nope' }, null, {
+      spawnSyncImpl: () => ({ status: 0 }),
+    });
+
+    expect(handled).toBe(false);
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('resolveClient', () => {
+  class FakeClient {
+    constructor(options) {
+      this.options = options;
+    }
+  }
+
+  it('returns the injected client when it has a send method', () => {
+    const injected = { send: () => {} };
+    expect(resolveClient(injected, FakeClient, { region: 'us-east-2' })).toBe(injected);
+  });
+
+  it('constructs the client when nothing usable is injected', () => {
+    const built = resolveClient(undefined, FakeClient, { region: 'eu-west-1' });
+    expect(built).toBeInstanceOf(FakeClient);
+    expect(built.options).toEqual({ region: 'eu-west-1' });
+  });
+
+  it('constructs the client when the injected value has no send method', () => {
+    expect(resolveClient({ not: 'a-client' }, FakeClient)).toBeInstanceOf(FakeClient);
+    expect(resolveClient(null, FakeClient)).toBeInstanceOf(FakeClient);
+  });
+});
+
+describe('hasAwsCli result cache', () => {
+  beforeEach(() => {
+    resetAwsCliCache();
+    mockSpawnSync.mockReset().mockReturnValue({ status: 0 });
+  });
+
+  it('spawns once for repeated default calls within the TTL', () => {
+    expect(hasAwsCli()).toBe(true);
+    expect(hasAwsCli()).toBe(true);
+    expect(hasAwsCli({})).toBe(true);
+    expect(mockSpawnSync).toHaveBeenCalledTimes(1);
+    expect(mockSpawnSync).toHaveBeenCalledWith('aws', ['--version'], { stdio: 'ignore' });
+  });
+
+  it('spawns again after resetAwsCliCache()', () => {
+    expect(hasAwsCli()).toBe(true);
+    expect(mockSpawnSync).toHaveBeenCalledTimes(1);
+    resetAwsCliCache();
+    expect(hasAwsCli()).toBe(true);
+    expect(mockSpawnSync).toHaveBeenCalledTimes(2);
+  });
+
+  it('bypasses the cache for custom spawnSyncImpl without polluting it', () => {
+    expect(hasAwsCli({ spawnSyncImpl: () => ({ status: 1 }) })).toBe(false);
+    expect(hasAwsCli({ spawnSyncImpl: () => ({ status: 0 }) })).toBe(true);
+    expect(mockSpawnSync).not.toHaveBeenCalled();
+    expect(hasAwsCli()).toBe(true);
+    expect(mockSpawnSync).toHaveBeenCalledTimes(1);
+  });
+});

package/tests/capabilities.test.js

@@ -0,0 +1,307 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { detectProjectCapabilities } from '../src/utils/capabilities.js';
+
+let tmpDirs = [];
+
+function makeTmp() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'capabilities-test-'));
+    tmpDirs.push(dir);
+    return dir;
+}
+
+function writeFile(dir, relPath, content) {
+    const full = path.join(dir, relPath);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+    return full;
+}
+
+function writeJson(dir, relPath, value) {
+    return writeFile(dir, relPath, JSON.stringify(value, null, 2));
+}
+
+beforeEach(() => {
+    tmpDirs = [];
+});
+
+afterEach(() => {
+    for (const dir of tmpDirs) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+
+describe('detectProjectCapabilities: empty and malformed projects', () => {
+    it('returns a blank shape for an empty directory', () => {
+        const result = detectProjectCapabilities(makeTmp());
+        expect(result.relationalDb).toEqual({ detected: false, evidence: [] });
+        expect(result.worker).toEqual({ detected: false, suggestedCommand: null, evidence: [] });
+        expect(result.migration).toEqual({ detected: false, command: null });
+        expect(result.upcomingHints).toEqual({ vector: false, cron: false, mysql: false });
+        expect(Object.keys(result.addons)).toEqual([
+            'storage:s3', 'db:dynamodb', 'db:redis', 'queue:sqs', 'ai:bedrock', 'email:ses', 'cron',
+        ]);
+        for (const addon of Object.values(result.addons)) {
+            expect(addon).toEqual({ detected: false, evidence: [] });
+        }
+    });
+
+    it('never throws on malformed manifests', () => {
+        const dir = makeTmp();
+        writeFile(dir, 'package.json', '{not json');
+        writeFile(dir, 'requirements.txt', '\x00\x01binary');
+        writeFile(dir, 'go.mod', '((((');
+        writeFile(dir, 'vercel.json', '[unclosed');
+        writeFile(dir, 'docker-compose.yml', ':\t: bad: [yaml');
+        expect(() => detectProjectCapabilities(dir)).not.toThrow();
+        const result = detectProjectCapabilities(dir);
+        expect(result.relationalDb.detected).toBe(false);
+        expect(result.migration.detected).toBe(false);
+    });
+});
+
+describe('detectProjectCapabilities: relational database signals', () => {
+    it('detects Node postgres drivers by exact key', () => {
+        const dir = makeTmp();
+        writeJson(dir, 'package.json', { dependencies: { pg: '^8.0.0' }, devDependencies: { 'drizzle-kit': '^1.0.0' } });
+        const result = detectProjectCapabilities(dir);
+        expect(result.relationalDb.detected).toBe(true);
+        expect(result.relationalDb.evidence).toContain('pg');
+        expect(result.relationalDb.evidence).toContain('drizzle-kit');
+    });
+
+    it('detects Python, Go, and Ruby postgres signals with normalization', () => {
+        const dir = makeTmp();
+        writeFile(dir, 'requirements.txt', 'psycopg2-binary==2.9.9\nDjango>=4.0\n');
+        writeFile(dir, 'go.mod', 'module example.com/app\n\ngo 1.21\n\nrequire github.com/jackc/pgx/v5 v5.0.0\n');
+        writeFile(dir, 'Gemfile', "source 'https://rubygems.org'\ngem 'rails', '~> 7.0'\n");
+        const result = detectProjectCapabilities(dir);
+        expect(result.relationalDb.detected).toBe(true);
+        expect(result.relationalDb.evidence).toContain('psycopg2-binary');
+        expect(result.relationalDb.evidence).toContain('django');
+        expect(result.relationalDb.evidence).not.toContain('github.com/jackc/pgx/v5');
+        // pgx v5 module path is distinct from the listed v4 signal
+        expect(result.relationalDb.evidence).toContain('rails');
+    });
+
+    it('detects pyproject.toml and Pipfile dependencies', () => {
+        const dir = makeTmp();
+        writeFile(dir, 'pyproject.toml', '[project]\ndependencies = [\n  "sqlalchemy>=2.0",\n  "alembic",\n]\n');
+        const fromPyproject = detectProjectCapabilities(dir);
+        expect(fromPyproject.relationalDb.evidence).toContain('sqlalchemy');
+        expect(fromPyproject.relationalDb.evidence).toContain('alembic');
+
+        const dir2 = makeTmp();
+        writeFile(dir2, 'Pipfile', '[packages]\nasyncpg = "*"\n');
+        expect(detectProjectCapabilities(dir2).relationalDb.evidence).toContain('asyncpg');
+    });
+
+    it('triggers on Drizzle, Alembic, Django, and Rails markers', () => {
+        for (const marker of ['drizzle.config.ts', 'alembic.ini', 'manage.py', 'bin/rails']) {
+            const dir = makeTmp();
+            writeFile(dir, marker, '# marker');
+            const result = detectProjectCapabilities(dir);
+            expect(result.relationalDb.detected).toBe(true);
+            expect(result.relationalDb.evidence).toContain(marker);
+        }
+    });
+
+    it('honors the prisma provider: postgres yes, mysql/sqlite/mongodb no', () => {
+        const withProvider = (provider) => {
+            const dir = makeTmp();
+            writeJson(dir, 'package.json', { dependencies: { '@prisma/client': '^5.0.0' } });
+            writeFile(dir, 'prisma/schema.prisma', `datasource db {\n  provider = "${provider}"\n}\n`);
+            return detectProjectCapabilities(dir);
+        };
+        expect(withProvider('postgresql').relationalDb.detected).toBe(true);
+        expect(withProvider('postgresql').relationalDb.evidence).toContain('prisma/schema.prisma');
+        expect(withProvider('mysql').relationalDb.detected).toBe(false);
+        expect(withProvider('mysql').upcomingHints.mysql).toBe(true);
+        expect(withProvider('sqlite').relationalDb.detected).toBe(false);
+        expect(withProvider('mongodb').relationalDb.detected).toBe(false);
+
+        // Bare client without a schema still counts as relational.
+        const bare = makeTmp();
+        writeJson(bare, 'package.json', { dependencies: { prisma: '^5.0.0' } });
+        expect(detectProjectCapabilities(bare).relationalDb.detected).toBe(true);
+    });
+
+    it('detects compose postgres images and env keys', () => {
+        const dir = makeTmp();
+        writeFile(dir, 'docker-compose.yml', 'services:\n  db:\n    image: postgis/postgis:16-3.4\n');
+        writeFile(dir, '.env.example', 'DATABASE_URL=postgresql://user:pass@localhost/db\n');
+        const result = detectProjectCapabilities(dir);
+        expect(result.relationalDb.evidence).toContain('docker-compose postgis/postgis');
+        expect(result.relationalDb.evidence).toContain('DATABASE_URL');
+    });
+
+    it('keeps MySQL-only projects out of relationalDb with a mysql hint', () => {
+        const dir = makeTmp();
+        writeJson(dir, 'package.json', { dependencies: { mysql2: '^3.0.0' } });
+        writeFile(dir, '.env.example', 'MYSQL_URL=mysql://user:pass@localhost/db\n');
+        const result = detectProjectCapabilities(dir);
+        expect(result.relationalDb.detected).toBe(false);
+        expect(result.upcomingHints.mysql).toBe(true);
+
+        const both = makeTmp();
+        writeJson(both, 'package.json', { dependencies: { pg: '^8.0.0', mysql2: '^3.0.0' } });
+        const mixed = detectProjectCapabilities(both);
+        expect(mixed.relationalDb.detected).toBe(true);
+        expect(mixed.upcomingHints.mysql).toBe(true);
+    });
+});
+
+describe('detectProjectCapabilities: addon signals', () => {
+    it('detects redis across ecosystems, compose, and env keys', () => {
+        const dir = makeTmp();
+        writeJson(dir, 'package.json', { dependencies: { ioredis: '^5.0.0', bullmq: '^5.0.0' } });
+        writeFile(dir, 'requirements.txt', 'celery\nredis\n');
+        writeFile(dir, 'compose.yaml', 'services:\n  cache:\n    image: valkey/valkey:8\n');
+        const result = detectProjectCapabilities(dir);
+        expect(result.addons['db:redis'].detected).toBe(true);
+        expect(result.addons['db:redis'].evidence).toEqual(
+            expect.arrayContaining(['ioredis', 'bullmq', 'redis', 'celery', 'docker-compose valkey/valkey'])
+        );
+    });
+
+    it('requires celery+redis co-presence for the celery redis signal', () => {
+        const alone = makeTmp();
+        writeFile(alone, 'requirements.txt', 'celery\n');
+        expect(detectProjectCapabilities(alone).addons['db:redis'].detected).toBe(false);
+    });
+
+    it('detects sqs, s3, dynamodb, bedrock, and ses signals', () => {
+        const dir = makeTmp();
+        writeJson(dir, 'package.json', {
+            dependencies: {
+                '@aws-sdk/client-sqs': '^3.0.0',
+                '@aws-sdk/client-s3': '^3.0.0',
+                '@aws-sdk/client-dynamodb': '^3.0.0',
+                '@aws-sdk/client-bedrock-runtime': '^3.0.0',
+                '@aws-sdk/client-sesv2': '^3.0.0',
+            },
+        });
+        writeFile(dir, 'Gemfile', "gem 'shoryuken'\ngem 'aws-sdk-ses'\ngem 'aws-sdk-bedrockruntime'\ngem 'aws-sdk-dynamodb'\n");
+        const result = detectProjectCapabilities(dir);
+        expect(result.addons['queue:sqs'].evidence).toEqual(expect.arrayContaining(['@aws-sdk/client-sqs', 'shoryuken']));
+        expect(result.addons['storage:s3'].evidence).toContain('@aws-sdk/client-s3');
+        expect(result.addons['db:dynamodb'].evidence).toEqual(
+            expect.arrayContaining(['@aws-sdk/client-dynamodb', 'aws-sdk-dynamodb'])
+        );
+        expect(result.addons['ai:bedrock'].evidence).toEqual(
+            expect.arrayContaining(['@aws-sdk/client-bedrock-runtime', 'aws-sdk-bedrockruntime'])
+        );
+        expect(result.addons['email:ses'].evidence).toEqual(
+            expect.arrayContaining(['@aws-sdk/client-sesv2', 'aws-sdk-ses'])
+        );
+    });
+
+    it('detects localstack only when SERVICES includes sqs', () => {
+        const withSqs = makeTmp();
+        writeFile(withSqs, 'docker-compose.yml', 'services:\n  aws:\n    image: localstack/localstack:3\n    environment:\n      SERVICES: s3,sqs\n');
+        expect(detectProjectCapabilities(withSqs).addons['queue:sqs'].evidence)
+            .toContain('docker-compose localstack');
+
+        const withoutSqs = makeTmp();
+        writeFile(withoutSqs, 'docker-compose.yml', 'services:\n  aws:\n    image: localstack/localstack:3\n    environment:\n      SERVICES: s3\n');
+        expect(detectProjectCapabilities(withoutSqs).addons['queue:sqs'].detected).toBe(false);
+
+        const bare = makeTmp();
+        writeFile(bare, 'docker-compose.yml', 'services:\n  aws:\n    image: localstack/localstack:3\n');
+        expect(detectProjectCapabilities(bare).addons['queue:sqs'].evidence)
+            .toContain('docker-compose localstack');
+    });
+
+    it('detects minio, dynamodb-local, and ses env keys', () => {
+        const dir = makeTmp();
+        writeFile(dir, 'docker-compose.yml', 'services:\n  s3:\n    image: minio/minio:latest\n  ddb:\n    image: amazon/dynamodb-local:latest\n');
+        writeFile(dir, '.env.sample', 'export SES_FROM_EMAIL=noreply@example.com\nSES_REGION=us-east-2\n');
+        const result = detectProjectCapabilities(dir);
+        expect(result.addons['storage:s3'].evidence).toContain('docker-compose minio/minio');
+        expect(result.addons['db:dynamodb'].evidence).toContain('docker-compose amazon/dynamodb-local');
+        expect(result.addons['email:ses'].evidence).toEqual(expect.arrayContaining(['SES_FROM_EMAIL', 'SES_REGION']));
+    });
+});
+
+describe('detectProjectCapabilities: tokenization and privacy', () => {
+    it('never fires on substring false-positives', () => {
+        const dir = makeTmp();
+        writeJson(dir, 'package.json', { dependencies: { 'node-cron-parser': '1.0.0', pgvector: '1.0.0' } });
+        writeFile(dir, 'requirements.txt', 'my-pg-helper\nnot-cron-at-all\n');
+        writeFile(dir, 'Gemfile', "gem 'pg_search'\n");
+        writeFile(dir, 'go.mod', 'module example.com/app\n\nrequire github.com/foo/pgbar v1.0.0\n');
+        const result = detectProjectCapabilities(dir);
+        expect(result.relationalDb.detected).toBe(false);
+        expect(result.upcomingHints.cron).toBe(false);
+        // pgvector is an exact package: vector hint yes, relational pg no.
+        expect(result.upcomingHints.vector).toBe(true);
+        expect(result.relationalDb.evidence).not.toContain('pg');
+    });
+
+    it('treats sidekiq-cron as cron only, not as sidekiq redis', () => {
+        const dir = makeTmp();
+        writeFile(dir, 'Gemfile', "gem 'sidekiq-cron'\n");
+        const result = detectProjectCapabilities(dir);
+        expect(result.upcomingHints.cron).toBe(true);
+        expect(result.addons['db:redis'].detected).toBe(false);
+    });
+
+    it('reads env key names but never values', () => {
+        const dir = makeTmp();
+        writeFile(dir, '.env', 'REDIS_URL=redis://:s3cret-pw@db.internal:6379/0\n');
+        writeFile(dir, '.env.example', 'FOO=SQS_QUEUE_URL\n# SQS_DLQ_URL=commented-out\n');
+        const result = detectProjectCapabilities(dir);
+        expect(result.addons['db:redis'].evidence).toContain('REDIS_URL');
+        // A signal appearing as a VALUE (or in a comment) must not fire.
+        expect(result.addons['queue:sqs'].detected).toBe(false);
+        expect(JSON.stringify(result)).not.toContain('s3cret-pw');
+        expect(JSON.stringify(result)).not.toContain('db.internal');
+    });
+});
+
+describe('detectProjectCapabilities: worker, migration, and hints', () => {
+    it('suggests npm run commands from worker-ish script names and bodies', () => {
+        const byName = makeTmp();
+        writeJson(byName, 'package.json', { scripts: { start: 'node index.js', 'queue:work': 'node queue.js' } });
+        const named = detectProjectCapabilities(byName);
+        expect(named.worker.detected).toBe(true);
+        expect(named.worker.suggestedCommand).toBe('npm run queue:work');
+
+        const byBody = makeTmp();
+        writeJson(byBody, 'package.json', { scripts: { jobs: 'node bull-board.js' } });
+        expect(detectProjectCapabilities(byBody).worker.suggestedCommand).toBe('npm run jobs');
+    });
+
+    it('detects worker deps, Procfile workers, and compose worker services', () => {
+        const dir = makeTmp();
+        writeFile(dir, 'requirements.txt', 'dramatiq\n');
+        writeFile(dir, 'Procfile', 'web: gunicorn app.wsgi\nworker: celery -A app worker\n');
+        writeFile(dir, 'docker-compose.yml', 'services:\n  web:\n    image: app:latest\n    ports: ["3000:3000"]\n  mail-worker:\n    image: app:latest\n');
+        const result = detectProjectCapabilities(dir);
+        expect(result.worker.detected).toBe(true);
+        expect(result.worker.evidence).toEqual(expect.arrayContaining(['dramatiq', 'Procfile', 'docker-compose worker']));
+    });
+
+    it('delegates migration detection to detectMigrationCommand', () => {
+        const dir = makeTmp();
+        writeJson(dir, 'package.json', { scripts: { 'db:migrate': 'prisma migrate deploy' } });
+        const result = detectProjectCapabilities(dir);
+        expect(result.migration.detected).toBe(true);
+        expect(result.migration.command).toContain('db:migrate');
+    });
+
+    it('detects vector and cron hints across ecosystems', () => {
+        const dir = makeTmp();
+        writeFile(dir, 'requirements.txt', 'pgvector\napscheduler\n');
+        writeFile(dir, 'docker-compose.yml', 'services:\n  db:\n    image: pgvector/pgvector:pg16\n');
+        writeFile(dir, 'vercel.json', JSON.stringify({ crons: [{ path: '/api/cron', schedule: '0 5 * * *' }] }));
+        const result = detectProjectCapabilities(dir);
+        expect(result.upcomingHints).toEqual({ vector: true, cron: true, mysql: false });
+
+        const emptyCrons = makeTmp();
+        writeFile(emptyCrons, 'vercel.json', JSON.stringify({ crons: [] }));
+        expect(detectProjectCapabilities(emptyCrons).upcomingHints.cron).toBe(false);
+    });
+});

package/tests/cli.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+
+describe('CLI Executable', () => {
+    it('must have the Node.js shebang at the top to prevent bash execution errors', () => {
+        const cliPath = path.resolve(__dirname, '../bin/cli.js');
+        const content = fs.readFileSync(cliPath, 'utf8');
+
+        expect(content.startsWith('#!/usr/bin/env node')).toBe(true);
+    });
+
+    it('must have executable permissions', () => {
+        const cliPath = path.resolve(__dirname, '../bin/cli.js');
+        const stats = fs.statSync(cliPath);
+
+        // Checks if the file is executable by the owner (Unix permission check)
+        const isExecutable = (stats.mode & fs.constants.S_IXUSR) !== 0;
+        expect(isExecutable).toBe(true);
+    });
+
+    it('documents the --target chooser in help text', () => {
+        const cliPath = path.resolve(__dirname, '../bin/cli.js');
+        const content = fs.readFileSync(cliPath, 'utf8');
+
+        expect(content).toContain('--target <ecs|lambda>');
+        expect(content).toContain('Fargate vs Lambda');
+    });
+});

package/tests/command.test.js

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { failCommand, failProjectNotInitialized } from '../src/utils/command.js';
+import { trackEvent, flushTelemetry } from '../src/core/telemetry.js';
+
+vi.mock('../src/core/telemetry.js', () => ({
+    trackEvent: vi.fn(),
+    flushTelemetry: vi.fn().mockResolvedValue(),
+}));
+
+describe('failCommand', () => {
+    let exitSpy;
+    let logSpy;
+    let errorSpy;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {});
+        logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        exitSpy.mockRestore();
+        logSpy.mockRestore();
+        errorSpy.mockRestore();
+    });
+
+    it('prints, tracks, flushes, exits, and returns the standard result', async () => {
+        const result = await failCommand({
+            message: '\n✖ Bad input.',
+            hint: '  Fix it.',
+            event: 'add_run',
+            telemetry: { capability: 'x', error_code: 'BAD' },
+            reason: 'bad-input',
+            resultExtra: { capability: 'x' },
+        });
+        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Bad input.'));
+        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Fix it.'));
+        expect(trackEvent).toHaveBeenCalledWith('add_run', {
+            capability: 'x',
+            error_code: 'BAD',
+            success: false,
+        });
+        expect(flushTelemetry).toHaveBeenCalled();
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        expect(result).toEqual({ ok: false, reason: 'bad-input', capability: 'x' });
+    });
+
+    it('supports custom printers, error stream, and tones', async () => {
+        const print = vi.fn();
+        await failCommand({ print, exitCode: 2 });
+        expect(print).toHaveBeenCalledTimes(1);
+        expect(logSpy).not.toHaveBeenCalled();
+        expect(trackEvent).not.toHaveBeenCalled();
+        expect(exitSpy).toHaveBeenCalledWith(2);
+
+        await failCommand({ message: 'warn', tone: 'yellow', useErrorStream: true, exitCode: null });
+        expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('warn'));
+        expect(exitSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('skips telemetry, exit, and reason when omitted', async () => {
+        const result = await failCommand({ message: 'soft', exitCode: null });
+        expect(trackEvent).not.toHaveBeenCalled();
+        expect(flushTelemetry).not.toHaveBeenCalled();
+        expect(exitSpy).not.toHaveBeenCalled();
+        expect(result).toEqual({ ok: false });
+    });
+
+    it('stamps errorCode and merges extra into telemetry', async () => {
+        await failCommand({
+            message: 'failed',
+            event: 'db_migrate_run',
+            telemetry: { cmd_source: 'explicit' },
+            errorCode: 'MIGRATION_TASK_FAILED',
+            extra: { exit_code: 3 },
+            reason: 'migration-task-failed',
+            exitCode: 3,
+        });
+        expect(trackEvent).toHaveBeenCalledWith('db_migrate_run', {
+            cmd_source: 'explicit',
+            error_code: 'MIGRATION_TASK_FAILED',
+            exit_code: 3,
+            success: false,
+        });
+        expect(exitSpy).toHaveBeenCalledWith(3);
+    });
+
+    it('failProjectNotInitialized emits the structured not-initialized failure', async () => {
+        const result = await failProjectNotInitialized({ event: 'logs_streamed' });
+        expect(result).toEqual({ ok: false, reason: 'project-not-initialized' });
+        expect(trackEvent).toHaveBeenCalledWith('logs_streamed', {
+            error_code: 'PROJECT_NOT_INITIALIZED',
+            success: false,
+        });
+        expect(flushTelemetry).toHaveBeenCalled();
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Could not determine the project'));
+    });
+});