@popoverai/dotrequirements 0.11.0

package/dist/utils/project-selector.js

@@ -0,0 +1,69 @@
+import { promptChoice } from './prompts.js';
+import { api } from '../convex.js';
+/**
+ * Prompt user to select a team from their available teams.
+ * Returns the team ID, or null if user cancels.
+ */
+export async function selectTeam(client) {
+    console.log('Fetching your teams...\n');
+    const teams = await client.query(api.teams.queries.listForUserWithUsage);
+    if (teams.length === 0) {
+        console.log('You are not a member of any teams.');
+        console.log('To create a team, visit: https://app.dotrequirements.io/teams/new\n');
+        return null;
+    }
+    const teamChoices = teams.map((team) => {
+        const limitDisplay = team.projectLimit === -1
+            ? 'unlimited'
+            : `${team.projectCount}/${team.projectLimit}`;
+        return {
+            title: `${team.name} (${team.tierName} - ${limitDisplay} projects)`,
+            value: team.teamId,
+        };
+    });
+    const selectedTeamId = await promptChoice('Select a team:', teamChoices);
+    return selectedTeamId ?? null;
+}
+/**
+ * Prompt user to select a project from a team.
+ * Returns the selected project info, or null if user cancels or no projects exist.
+ */
+export async function selectProject(client, teamId) {
+    console.log('\nFetching projects...\n');
+    const projectsWithSecrets = await client.query(api.projectSecrets.queries.listOwnSecretsForTeam, { target: { type: 'team', id: teamId } });
+    if (projectsWithSecrets.length === 0) {
+        console.log('No projects found in this team.');
+        console.log('Use "dotrequirements init" to create a new project.\n');
+        return null;
+    }
+    const projectChoices = projectsWithSecrets.map((project) => ({
+        title: project.projectSlug
+            ? `${project.projectName} (${project.projectSlug})`
+            : project.projectName,
+        value: project.projectId,
+    }));
+    const selectedProjectId = await promptChoice('Select a project:', projectChoices);
+    if (!selectedProjectId) {
+        return null;
+    }
+    const selectedProject = projectsWithSecrets.find((p) => p.projectId === selectedProjectId);
+    if (!selectedProject) {
+        return null;
+    }
+    return {
+        projectId: selectedProject.projectId,
+        projectName: selectedProject.projectName,
+        projectSlug: selectedProject.projectSlug,
+    };
+}
+/**
+ * Get or create a user-scoped secret for a project.
+ * Returns the secret and whether it was newly created.
+ */
+export async function getOrCreateProjectSecret(client, projectId) {
+    const result = await client.mutation(api.projectSecrets.mutations.ensureOwnSecret, {
+        target: { type: 'project', id: projectId },
+    });
+    return result;
+}
+//# sourceMappingURL=project-selector.js.map

package/dist/utils/prompts.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Interactive prompt utilities for the CLI.
+ * Uses the prompts library for user interaction.
+ */
+/**
+ * Prompt the user to choose from a list of options.
+ * Returns the selected value.
+ */
+export declare function promptChoice<T extends string>(message: string, choices: Array<{
+    title: string;
+    value: T;
+    description?: string;
+    disabled?: boolean;
+}>): Promise<T | undefined>;
+/**
+ * Prompt the user for text input.
+ * Returns the entered text or undefined if cancelled.
+ */
+export declare function promptText(message: string, options?: {
+    initial?: string;
+    validate?: (value: string) => boolean | string;
+}): Promise<string | undefined>;
+/**
+ * Prompt the user for confirmation (yes/no).
+ * Returns true if confirmed, false otherwise.
+ */
+export declare function promptConfirm(message: string, initial?: boolean): Promise<boolean>;
+/**
+ * Prompt for password/secret input (hidden).
+ * Returns the entered secret or undefined if cancelled.
+ */
+export declare function promptSecret(message: string): Promise<string | undefined>;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/utils/prompts.js

@@ -0,0 +1,60 @@
+/**
+ * Interactive prompt utilities for the CLI.
+ * Uses the prompts library for user interaction.
+ */
+import prompts from "prompts";
+/**
+ * Prompt the user to choose from a list of options.
+ * Returns the selected value.
+ */
+export async function promptChoice(message, choices) {
+    const response = await prompts({
+        type: "select",
+        name: "value",
+        message,
+        choices,
+        initial: 0,
+    });
+    return response.value;
+}
+/**
+ * Prompt the user for text input.
+ * Returns the entered text or undefined if cancelled.
+ */
+export async function promptText(message, options) {
+    const response = await prompts({
+        type: "text",
+        name: "value",
+        message,
+        initial: options?.initial,
+        validate: options?.validate,
+    });
+    return response.value;
+}
+/**
+ * Prompt the user for confirmation (yes/no).
+ * Returns true if confirmed, false otherwise.
+ */
+export async function promptConfirm(message, initial = false) {
+    const response = await prompts({
+        type: "confirm",
+        name: "value",
+        message,
+        initial,
+    });
+    // If user cancels (Ctrl+C), treat as false
+    return response.value ?? false;
+}
+/**
+ * Prompt for password/secret input (hidden).
+ * Returns the entered secret or undefined if cancelled.
+ */
+export async function promptSecret(message) {
+    const response = await prompts({
+        type: "password",
+        name: "value",
+        message,
+    });
+    return response.value;
+}
+//# sourceMappingURL=prompts.js.map

package/dist/utils/templates.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Load a template file and replace placeholders
+ */
+export declare function loadTemplate(templateName: string, replacements?: Record<string, string>): string;
+/**
+ * Load the behavioral core content (requirements capture guidance)
+ */
+export declare function loadBehavioralCore(): string;
+/**
+ * Load the test writing core content
+ */
+export declare function loadTestWritingCore(): string;
+/**
+ * Load the overview core content
+ */
+export declare function loadOverviewCore(): string;
+/**
+ * Load the requirements skill template with core content injected
+ */
+export declare function loadPlatformTemplate(templateName: string): string;
+/**
+ * Load the test writing skill template with core content injected
+ */
+export declare function loadTestWritingTemplate(templateName: string): string;
+/**
+ * Load the overview skill template with core content injected
+ */
+export declare function loadOverviewTemplate(templateName: string): string;
+//# sourceMappingURL=templates.d.ts.map

package/dist/utils/templates.js

@@ -0,0 +1,67 @@
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+/**
+ * Get the templates directory path
+ */
+function getTemplatesDir() {
+    // In production (compiled), templates are in dist/templates
+    // In development, they're in src/templates
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    // Go up from utils/ to src/ or dist/, then into templates/
+    return join(__dirname, '..', 'templates');
+}
+/**
+ * Load a template file and replace placeholders
+ */
+export function loadTemplate(templateName, replacements = {}) {
+    const templatesDir = getTemplatesDir();
+    const templatePath = join(templatesDir, templateName);
+    let content = readFileSync(templatePath, 'utf-8');
+    // Replace placeholders
+    for (const [key, value] of Object.entries(replacements)) {
+        content = content.replace(new RegExp(`{{${key}}}`, 'g'), value);
+    }
+    return content;
+}
+/**
+ * Load the behavioral core content (requirements capture guidance)
+ */
+export function loadBehavioralCore() {
+    return loadTemplate('behavioral-core.md');
+}
+/**
+ * Load the test writing core content
+ */
+export function loadTestWritingCore() {
+    return loadTemplate('test-writing-core.md');
+}
+/**
+ * Load the overview core content
+ */
+export function loadOverviewCore() {
+    return loadTemplate('overview-core.md');
+}
+/**
+ * Load the requirements skill template with core content injected
+ */
+export function loadPlatformTemplate(templateName) {
+    const behavioralCore = loadBehavioralCore();
+    return loadTemplate(templateName, { BEHAVIORAL_CORE: behavioralCore });
+}
+/**
+ * Load the test writing skill template with core content injected
+ */
+export function loadTestWritingTemplate(templateName) {
+    const testWritingCore = loadTestWritingCore();
+    return loadTemplate(templateName, { TEST_WRITING_CORE: testWritingCore });
+}
+/**
+ * Load the overview skill template with core content injected
+ */
+export function loadOverviewTemplate(templateName) {
+    const overviewCore = loadOverviewCore();
+    return loadTemplate(templateName, { OVERVIEW_CORE: overviewCore });
+}
+//# sourceMappingURL=templates.js.map

package/dist/utils/token-refresh.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Token refresh utilities for maintaining long-lived CLI sessions.
+ *
+ * WorkOS access tokens expire after 5 minutes, but refresh tokens can be used
+ * to obtain new access/refresh token pairs. Refresh tokens are single-use and
+ * get rotated on each refresh.
+ */
+/**
+ * Get a valid access token, refreshing if needed.
+ *
+ * This function should be called before making any authenticated Convex requests.
+ * It checks if the current access token is expired and refreshes it if necessary.
+ *
+ * Returns null if no tokens are stored (user needs to login).
+ */
+export declare function getValidAccessToken(): Promise<string | null>;
+/**
+ * Ensure user is authenticated with a valid access token.
+ *
+ * Throws an error if not logged in or if token refresh fails.
+ * Use this at the start of commands that require authentication.
+ */
+export declare function requireAuth(): Promise<string>;
+//# sourceMappingURL=token-refresh.d.ts.map

package/dist/utils/token-refresh.js

@@ -0,0 +1,69 @@
+/**
+ * Token refresh utilities for maintaining long-lived CLI sessions.
+ *
+ * WorkOS access tokens expire after 5 minutes, but refresh tokens can be used
+ * to obtain new access/refresh token pairs. Refresh tokens are single-use and
+ * get rotated on each refresh.
+ */
+import { ConvexHttpClient } from 'convex/browser';
+import { getTokens, storeTokens, areTokensExpired } from './token-storage.js';
+import { getConvexUrl } from '../config.js';
+import { api } from '../convex.js';
+/**
+ * Get a valid access token, refreshing if needed.
+ *
+ * This function should be called before making any authenticated Convex requests.
+ * It checks if the current access token is expired and refreshes it if necessary.
+ *
+ * Returns null if no tokens are stored (user needs to login).
+ */
+export async function getValidAccessToken() {
+    const tokens = await getTokens();
+    if (!tokens) {
+        return null; // Not logged in
+    }
+    // If tokens are still valid, return current access token
+    if (!areTokensExpired(tokens)) {
+        return tokens.accessToken;
+    }
+    // Tokens expired, refresh them
+    try {
+        console.log('Access token expired, refreshing...');
+        // Refresh tokens via Convex action (server-side WorkOS call)
+        const client = new ConvexHttpClient(getConvexUrl());
+        const result = await client.action(api.lib.authActions.refreshAccessToken, {
+            refreshToken: tokens.refreshToken,
+        });
+        if (!result.success) {
+            throw new Error(`Token refresh failed: ${result.error}`);
+        }
+        const { accessToken, refreshToken, expiresAt } = result;
+        // Store new tokens (IMPORTANT: refresh token is single-use, must update)
+        await storeTokens({
+            accessToken,
+            refreshToken, // New refresh token from response
+            expiresAt,
+        });
+        console.log('✓ Token refreshed successfully');
+        return accessToken;
+    }
+    catch (error) {
+        console.error('Failed to refresh access token:', error);
+        console.log('Please run "dotrequirements login" to re-authenticate.');
+        return null;
+    }
+}
+/**
+ * Ensure user is authenticated with a valid access token.
+ *
+ * Throws an error if not logged in or if token refresh fails.
+ * Use this at the start of commands that require authentication.
+ */
+export async function requireAuth() {
+    const accessToken = await getValidAccessToken();
+    if (!accessToken) {
+        throw new Error('Not authenticated. Please run "dotrequirements login" first.');
+    }
+    return accessToken;
+}
+//# sourceMappingURL=token-refresh.js.map

package/dist/utils/token-storage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Token storage utilities for OAuth access tokens and refresh tokens.
+ *
+ * Uses file-based storage at ~/.dotrequirements/tokens.json with restricted permissions.
+ */
+export interface StoredTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+/**
+ * Store tokens in file storage with restricted permissions
+ */
+export declare function storeTokens(tokens: StoredTokens): Promise<void>;
+/**
+ * Retrieve stored tokens from file
+ */
+export declare function getTokens(): Promise<StoredTokens | null>;
+/**
+ * Delete stored tokens
+ */
+export declare function deleteTokens(): Promise<void>;
+/**
+ * Check if tokens are expired
+ */
+export declare function areTokensExpired(tokens: StoredTokens): boolean;
+/**
+ * Check if tokens exist and are valid
+ */
+export declare function hasValidTokens(): Promise<boolean>;
+//# sourceMappingURL=token-storage.d.ts.map

package/dist/utils/token-storage.js

@@ -0,0 +1,57 @@
+/**
+ * Token storage utilities for OAuth access tokens and refresh tokens.
+ *
+ * Uses file-based storage at ~/.dotrequirements/tokens.json with restricted permissions.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const TOKEN_DIR = path.join(os.homedir(), '.dotrequirements');
+const TOKEN_FILE = path.join(TOKEN_DIR, 'tokens.json');
+/**
+ * Store tokens in file storage with restricted permissions
+ */
+export async function storeTokens(tokens) {
+    if (!fs.existsSync(TOKEN_DIR)) {
+        fs.mkdirSync(TOKEN_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(TOKEN_FILE, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+}
+/**
+ * Retrieve stored tokens from file
+ */
+export async function getTokens() {
+    if (fs.existsSync(TOKEN_FILE)) {
+        try {
+            const content = fs.readFileSync(TOKEN_FILE, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            console.error('Failed to read stored tokens:', error);
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Delete stored tokens
+ */
+export async function deleteTokens() {
+    if (fs.existsSync(TOKEN_FILE)) {
+        fs.unlinkSync(TOKEN_FILE);
+    }
+}
+/**
+ * Check if tokens are expired
+ */
+export function areTokensExpired(tokens) {
+    return Date.now() >= tokens.expiresAt;
+}
+/**
+ * Check if tokens exist and are valid
+ */
+export async function hasValidTokens() {
+    const tokens = await getTokens();
+    return tokens !== null && !areTokensExpired(tokens);
+}
+//# sourceMappingURL=token-storage.js.map

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@popoverai/dotrequirements",
+  "version": "0.11.0",
+  "description": "Requirements tracking CLI, test harness, and MCP server",
+  "type": "module",
+  "bin": {
+    "dotrequirements": "./dist/cli.js",
+    "dotreq": "./dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/cli.js",
+    "./test": "./dist/harness/index.js",
+    "./schema": "./dist/schema/index.js",
+    "./schema/browser": "./dist/schema/browser.js",
+    "./mcp": "./dist/mcp/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && cp -r src/templates/* dist/templates/",
+    "dev": "tsc --watch",
+    "pull": "node dist/cli.js pull",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepublish:check": "git diff-index --quiet HEAD || (echo 'Error: Uncommitted changes detected. Commit or stash them first.' && exit 1)",
+    "publish:patch": "pnpm prepublish:check && npm version patch && pnpm build && npm publish && git push && git push --tags",
+    "publish:minor": "pnpm prepublish:check && npm version minor && pnpm build && npm publish && git push && git push --tags",
+    "publish:major": "pnpm prepublish:check && npm version major && pnpm build && npm publish && git push && git push --tags"
+  },
+  "keywords": [
+    "requirements",
+    "testing",
+    "test-coverage",
+    "bdd",
+    "tdd",
+    "mcp",
+    "ai-assistant"
+  ],
+  "author": "Will Raymer @Popover",
+  "license": "MIT",
+  "homepage": "https://dotrequirements.io",
+  "bugs": {
+    "email": "support@popover.ca"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.28.5",
+    "@babel/traverse": "^7.28.5",
+    "@babel/types": "^7.28.5",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@types/prompts": "^2.4.9",
+    "@workos-inc/node": "^7.77.0",
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "convex": "^1.29.3",
+    "find-up": "^8.0.0",
+    "glob": "^11.0.0",
+    "open": "^11.0.0",
+    "prompts": "^2.4.2",
+    "uuid": "^13.0.0",
+    "yaml": "^2.8.1",
+    "zod": "^3.25.76",
+    "zod-validation-error": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "^20",
+    "@types/uuid": "^11.0.0",
+    "typescript": "^5",
+    "vitest": "^4.0.0"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.js.map",
+    "!dist/**/*.d.ts.map"
+  ]
+}