@a-company/paradigm 5.11.0 → 5.21.0

package/dist/tutorial-KD22SUNO.js

@@ -1,666 +0,0 @@
-#!/usr/bin/env node
-import "./chunk-PDX44BCA.js";
-
-// src/commands/tutorial/index.ts
-import * as path from "path";
-import * as fs from "fs";
-import * as yaml from "js-yaml";
-import chalk from "chalk";
-import { execSync } from "child_process";
-var TUTORIAL_STATE_FILE = ".paradigm/tutorial/state.json";
-var CURRICULUM_FILE = ".paradigm/tutorial/curriculum.yaml";
-function loadState(rootDir) {
-  const statePath = path.join(rootDir, TUTORIAL_STATE_FILE);
-  if (fs.existsSync(statePath)) {
-    try {
-      return JSON.parse(fs.readFileSync(statePath, "utf8"));
-    } catch {
-    }
-  }
-  return {
-    currentStep: null,
-    completedSteps: [],
-    fixedBugs: []
-  };
-}
-function saveState(rootDir, state) {
-  const statePath = path.join(rootDir, TUTORIAL_STATE_FILE);
-  const stateDir = path.dirname(statePath);
-  if (!fs.existsSync(stateDir)) {
-    fs.mkdirSync(stateDir, { recursive: true });
-  }
-  fs.writeFileSync(statePath, JSON.stringify(state, null, 2), "utf8");
-}
-function generateDefaultCurriculum(rootDir) {
-  const tutorialDir = path.join(rootDir, ".paradigm/tutorial");
-  if (!fs.existsSync(tutorialDir)) {
-    fs.mkdirSync(tutorialDir, { recursive: true });
-  }
-  const curriculum = {
-    title: "Paradigm Tutorial - ShopFlow Example",
-    description: "Learn Paradigm by exploring the ShopFlow e-commerce example",
-    steps: [
-      {
-        id: "step-1-explore-structure",
-        title: "Explore Project Structure",
-        description: "Understand how Paradigm organizes project knowledge",
-        file: "step-1-explore-structure.md",
-        checkpoints: [
-          {
-            type: "file-exists",
-            path: ".purpose"
-          },
-          {
-            type: "file-exists",
-            path: "portal.yaml"
-          },
-          {
-            type: "file-exists",
-            path: ".paradigm/config.yaml"
-          }
-        ]
-      },
-      {
-        id: "step-2-understand-purpose",
-        title: "Understanding Purpose Files",
-        description: "Learn how Purpose files define features and components",
-        file: "step-2-understand-purpose.md",
-        checkpoints: [
-          {
-            type: "file-exists",
-            path: ".purpose"
-          }
-        ]
-      },
-      {
-        id: "step-3-understand-gates",
-        title: "Understanding Gates",
-        description: "Learn how Gates define authorization and access control",
-        file: "step-3-understand-gates.md",
-        checkpoints: [
-          {
-            type: "file-exists",
-            path: "portal.yaml"
-          }
-        ]
-      },
-      {
-        id: "step-4-explore-symbols",
-        title: "Exploring Symbols",
-        description: "Understand Paradigm's symbol system and how they connect",
-        file: "step-4-explore-symbols.md",
-        checkpoints: [
-          {
-            type: "command-success",
-            command: "paradigm status"
-          }
-        ]
-      },
-      {
-        id: "step-5-visualize",
-        title: "Visualize in Dreamscape",
-        description: "See your project knowledge visualized in the Dreamscape",
-        file: "step-5-visualize.md",
-        checkpoints: [
-          {
-            type: "command-success",
-            command: "paradigm dream aggregate"
-          }
-        ]
-      }
-    ],
-    bugs: []
-  };
-  const curriculumPath = path.join(tutorialDir, "curriculum.yaml");
-  fs.writeFileSync(curriculumPath, yaml.dump(curriculum), "utf8");
-  const stepFiles = [
-    {
-      file: "step-1-explore-structure.md",
-      content: `# Step 1: Explore Project Structure
-
-Welcome to the Paradigm tutorial! In this step, you'll explore how Paradigm organizes project knowledge.
-
-## What You'll Learn
-
-- How Paradigm uses files to structure project knowledge
-- The purpose of different Paradigm files
-- How to navigate a Paradigm project
-
-## Tasks
-
-1. **Examine the root .purpose file**
-   - Open \`.purpose\` in the root directory
-   - Notice how it defines features (\`@\`) and components (\`#\`)
-   - See how features reference components and gates
-
-2. **Check the portal.yaml file**
-   - Open \`portal.yaml\`
-   - Notice how gates (\`^\`) define authorization rules
-   - See how gates have locks, keys, and prizes
-
-3. **Explore .paradigm directory**
-   - Look at \`.paradigm/config.yaml\` - this is the Paradigm configuration
-   - Check \`.paradigm/specs/\` - these define the symbol system
-   - Browse \`.paradigm/docs/\` - reference documentation
-
-4. **Notice the nested structure**
-   - Check \`auth/.purpose\`, \`payments/.purpose\`, etc.
-   - See how Purpose files can be organized by domain
-
-## Checkpoint
-
-When you're ready, run:
-\`\`\`bash
-paradigm tutorial checkpoint
-\`\`\`
-
-This will verify you've explored the key files.
-`
-    },
-    {
-      file: "step-2-understand-purpose.md",
-      content: `# Step 2: Understanding Purpose Files
-
-Purpose files are the foundation of Paradigm. They define what your project does and how it's structured.
-
-## What You'll Learn
-
-- How Purpose files define features (\`@\`) and components (\`#\`)
-- How to read and understand Purpose file syntax
-- How features reference other symbols
-
-## Tasks
-
-1. **Read the root .purpose file**
-   - Open \`.purpose\` and read through it
-   - Identify all features (lines starting with \`- id: "@\`)
-   - Identify all components (lines starting with \`- id: "#\`)
-
-2. **Understand feature definitions**
-   - Look at \`@product-browse\` - what components does it use?
-   - Look at \`@checkout-flow\` - what gates does it require?
-   - Notice how features reference other features
-
-3. **Explore nested Purpose files**
-   - Open \`auth/.purpose\` - what features are defined here?
-   - Open \`payments/.purpose\` - how does it relate to checkout?
-   - See how domain-specific Purpose files organize knowledge
-
-4. **Trace a feature**
-   - Pick a feature like \`@checkout-flow\`
-   - Follow its references to see what it depends on
-   - Understand the relationships between features, components, and gates
-
-## Key Concepts
-
-- **Features (\`@\`)** - User-facing capabilities
-- **Components (\`#\`)** - Reusable code units
-- **References** - How features connect to components and gates
-
-## Checkpoint
-
-Run:
-\`\`\`bash
-paradigm tutorial checkpoint
-\`\`\`
-`
-    },
-    {
-      file: "step-3-understand-gates.md",
-      content: `# Step 3: Understanding Gates
-
-Gates define authorization and access control in Paradigm. They're like security checkpoints.
-
-## What You'll Learn
-
-- How gates (\`^\`) define access control
-- The structure of locks, keys, and prizes
-- How gates protect features
-
-## Tasks
-
-1. **Examine portal.yaml**
-   - Open \`portal.yaml\` and read through it
-   - Notice the structure: gates \u2192 locks \u2192 keys
-   - See how prizes are awarded when gates pass
-
-2. **Understand a simple gate**
-   - Look at \`^auth-required\`
-   - What lock does it have?
-   - What key expression checks authentication?
-   - What prize is awarded?
-
-3. **Explore a complex gate**
-   - Look at \`^admin-panel\`
-   - How many locks does it have?
-   - What conditions must be met?
-   - What prizes are available?
-
-4. **See gates in action**
-   - Go back to \`.purpose\` files
-   - Find features that reference gates (like \`^auth-required\`)
-   - Understand how gates protect features
-
-## Key Concepts
-
-- **Gates (\`^\`)** - Access control points
-- **Locks** - Conditions that must be met
-- **Keys** - Expressions that unlock locks
-- **Prizes** - Rewards when gates pass
-
-## Checkpoint
-
-Run:
-\`\`\`bash
-paradigm tutorial checkpoint
-\`\`\`
-`
-    },
-    {
-      file: "step-4-explore-symbols.md",
-      content: `# Step 4: Exploring Symbols
-
-Paradigm uses a symbol system to create a shared language between code, developers, and AI.
-
-## What You'll Learn
-
-- All the symbol types in Paradigm
-- Concatenated symbols (compound ideas like \`?@\`, \`?#\`, \`?!\`)
-- How symbols reference each other
-- How to use paradigm commands to explore symbols
-
-## Tasks
-
-1. **Run paradigm status**
-   \`\`\`bash
-   paradigm status
-   \`\`\`
-   - See how many features, components, gates, etc. are defined
-   - Notice the symbol counts
-
-2. **Understand symbol types**
-   - \`@\` - Features (user-facing capabilities)
-   - \`#\` - Components (reusable code units)
-   - \`$\` - Flows (multi-step processes)
-   - \`%\` - State (global/user state)
-   - \`~\` - Deprecated (marked for removal)
-   - \`^\` - Gates (access control)
-   - \`!\` - Signals (events/errors)
-   - \`?\` - Ideas (exploration)
-
-3. **Understand concatenated symbols (compound ideas)**
-   Ideas can specify what type of symbol they're exploring by using a compound prefix:
-   - \`?@subscription-model\` - Idea for a feature
-   - \`?#dark-mode-toggle\` - Idea for a component
-   - \`?$express-checkout\` - Idea for a flow
-   - \`?%user-preferences\` - Idea for state
-   - \`?~old-api-removal\` - Idea for deprecation
-   - \`?^premium-access\` - Idea for a gate
-   - \`?!payment-webhook\` - Idea for a signal
-   
-   **Why use compound ideas?**
-   - **Categorization**: Makes it clear what type of symbol the idea relates to
-   - **Discoverability**: In the Dreamscape visualizer, compound ideas connect to their target symbol type
-   - **Planning**: Helps organize ideas by what they would become if implemented
-   
-   **Simple vs Compound:**
-   - \`?subscription-model\` - General idea, no specific type
-   - \`?@subscription-model\` - Idea specifically for a feature
-
-4. **Trace symbol relationships**
-   - Pick a feature like \`@checkout-flow\`
-   - See what gates it requires
-   - See what components it uses
-   - See what flows it's part of
-   - Look for compound ideas in \`.premise\` files
-
-5. **Explore with paradigm commands**
-   \`\`\`bash
-   paradigm purpose validate
-   paradigm gate validate
-   \`\`\`
-   - Validate your Purpose files
-   - Validate your gate configuration
-
-## Key Concepts
-
-- Symbols create a traceable web of relationships
-- Compound ideas (\`?@\`, \`?#\`, etc.) categorize ideas by their target symbol type
-- In the Dreamscape visualizer, compound ideas visually connect to their symbol type
-- AI agents can follow these relationships
-- Symbols make project knowledge discoverable
-
-## Checkpoint
-
-Run:
-\`\`\`bash
-paradigm tutorial checkpoint
-\`\`\`
-`
-    },
-    {
-      file: "step-5-visualize.md",
-      content: `# Step 5: Visualize in Dreamscape
-
-The Dreamscape is Paradigm's infinite canvas where all project knowledge flows together.
-
-## What You'll Learn
-
-- How to aggregate all symbols into the Dreamscape
-- How to visualize your project knowledge
-- How to explore relationships visually
-
-## Tasks
-
-1. **Aggregate symbols**
-   \`\`\`bash
-   paradigm dream aggregate
-   \`\`\`
-   - This combines all Purpose and Gate files
-   - Creates a unified symbol index
-   - Prepares data for visualization
-
-2. **Open the Dreamscape**
-   \`\`\`bash
-   paradigm visualize
-   \`\`\`
-   - This opens the visualizer in your browser
-   - You'll see all your symbols as nodes
-   - Connections show relationships
-
-3. **Explore visually**
-   - Click on features to see their connections
-   - See how gates protect features
-   - Understand the flow of information
-   - Notice how everything connects
-
-4. **Understand the big picture**
-   - See how ShopFlow is structured
-   - Understand feature dependencies
-   - Visualize authorization topology
-
-## Key Concepts
-
-- The Dreamscape shows everything at once
-- Visual exploration helps understand relationships
-- Symbols become nodes, references become connections
-
-## Checkpoint
-
-Run:
-\`\`\`bash
-paradigm tutorial checkpoint
-\`\`\`
-
-## Next Steps
-
-Congratulations! You've completed the tutorial. You now understand:
-- How Paradigm structures project knowledge
-- How Purpose files define features and components
-- How Gates define authorization
-- How symbols create relationships
-- How to visualize everything in the Dreamscape
-
-Continue exploring ShopFlow, or start using Paradigm in your own projects!
-`
-    }
-  ];
-  for (const stepFile of stepFiles) {
-    const stepPath = path.join(tutorialDir, stepFile.file);
-    fs.writeFileSync(stepPath, stepFile.content, "utf8");
-  }
-}
-function loadCurriculum(rootDir) {
-  const curriculumPath = path.join(rootDir, CURRICULUM_FILE);
-  if (!fs.existsSync(curriculumPath)) {
-    generateDefaultCurriculum(rootDir);
-  }
-  return yaml.load(fs.readFileSync(curriculumPath, "utf8"));
-}
-async function validateCheckpoint(rootDir, stepId, curriculum) {
-  const step = curriculum.steps.find((s) => s.id === stepId);
-  if (!step) {
-    return false;
-  }
-  for (const checkpoint of step.checkpoints || []) {
-    switch (checkpoint.type) {
-      case "file-exists": {
-        const filePath = path.join(rootDir, checkpoint.path);
-        if (!fs.existsSync(filePath)) {
-          console.log(chalk.red(`\u274C Missing: ${checkpoint.path}`));
-          return false;
-        }
-        break;
-      }
-      case "symbol-count": {
-        break;
-      }
-      case "gate-count": {
-        break;
-      }
-      case "command-success": {
-        try {
-          execSync(checkpoint.command, { cwd: rootDir, stdio: "pipe" });
-        } catch {
-          console.log(chalk.red(`\u274C Command failed: ${checkpoint.command}`));
-          return false;
-        }
-        break;
-      }
-      case "bug-fixed": {
-        const state = loadState(rootDir);
-        if (!state.fixedBugs.includes(checkpoint.bug)) {
-          console.log(chalk.red(`\u274C Bug not fixed: ${checkpoint.bug}`));
-          return false;
-        }
-        break;
-      }
-    }
-  }
-  return true;
-}
-async function tutorialStartCommand(targetPath) {
-  const rootDir = targetPath ? path.resolve(targetPath) : process.cwd();
-  try {
-    const curriculumPath = path.join(rootDir, CURRICULUM_FILE);
-    if (!fs.existsSync(curriculumPath)) {
-      console.log(chalk.blue("\n\u{1F4DA} Generating tutorial curriculum...\n"));
-      generateDefaultCurriculum(rootDir);
-      console.log(chalk.green("\u2705 Tutorial curriculum generated!\n"));
-    }
-    const curriculum = loadCurriculum(rootDir);
-    const state = loadState(rootDir);
-    if (!state.currentStep && curriculum.steps.length > 0) {
-      state.currentStep = curriculum.steps[0].id;
-      saveState(rootDir, state);
-    }
-    console.log(chalk.blue("\n\u{1F393} Paradigm Tutorial\n"));
-    console.log(`Current Step: ${state.currentStep || "Not started"}`);
-    console.log(`Completed Steps: ${state.completedSteps.length}/${curriculum.steps.length}
-`);
-    if (state.currentStep) {
-      const step = curriculum.steps.find((s) => s.id === state.currentStep);
-      if (step) {
-        const stepFile = path.join(rootDir, ".paradigm/tutorial", step.file);
-        if (fs.existsSync(stepFile)) {
-          console.log(chalk.cyan(`\u{1F4D6} ${step.title}`));
-          console.log(chalk.gray(step.description));
-          console.log(chalk.gray(`
-View full instructions: ${stepFile}
-`));
-        }
-      }
-    }
-    console.log("Commands:");
-    console.log("  paradigm tutorial step <n>     Show step n");
-    console.log("  paradigm tutorial checkpoint   Validate current checkpoint");
-    console.log("  paradigm tutorial next         Move to next step");
-    console.log("  paradigm tutorial status       Show progress");
-    console.log("  paradigm tutorial reset        Reset tutorial\n");
-  } catch (error) {
-    console.error(chalk.red(`\u274C Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-async function tutorialStepCommand(targetPath, stepNum) {
-  const rootDir = targetPath ? path.resolve(targetPath) : process.cwd();
-  try {
-    const curriculum = loadCurriculum(rootDir);
-    const stepIndex = stepNum ? parseInt(stepNum, 10) - 1 : 0;
-    if (stepIndex < 0 || stepIndex >= curriculum.steps.length) {
-      console.error(chalk.red(`\u274C Invalid step number: ${stepNum}`));
-      process.exit(1);
-    }
-    const step = curriculum.steps[stepIndex];
-    const stepFile = path.join(rootDir, ".paradigm/tutorial", step.file);
-    if (fs.existsSync(stepFile)) {
-      console.log(chalk.blue(`
-\u{1F4D6} Step ${stepIndex + 1}: ${step.title}
-`));
-      const content = fs.readFileSync(stepFile, "utf8");
-      console.log(content);
-    } else {
-      console.error(chalk.red(`\u274C Step file not found: ${stepFile}`));
-      process.exit(1);
-    }
-  } catch (error) {
-    console.error(chalk.red(`\u274C Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-async function tutorialCheckpointCommand(targetPath) {
-  const rootDir = targetPath ? path.resolve(targetPath) : process.cwd();
-  try {
-    const curriculum = loadCurriculum(rootDir);
-    const state = loadState(rootDir);
-    if (!state.currentStep) {
-      console.log(chalk.yellow("\u26A0\uFE0F  No active step. Run `paradigm tutorial start` first."));
-      return;
-    }
-    console.log(chalk.blue(`
-\u{1F50D} Validating checkpoint for step: ${state.currentStep}
-`));
-    const passed = await validateCheckpoint(rootDir, state.currentStep, curriculum);
-    if (passed) {
-      console.log(chalk.green("\u2705 All checkpoints passed!\n"));
-      const currentIndex = curriculum.steps.findIndex((s) => s.id === state.currentStep);
-      if (currentIndex < curriculum.steps.length - 1) {
-        const nextStep = curriculum.steps[currentIndex + 1];
-        const nextStepFile = path.join(rootDir, ".paradigm/tutorial", nextStep.file);
-        if (fs.existsSync(nextStepFile)) {
-          console.log(chalk.cyan(`
-\u{1F4D6} Next Step: ${nextStep.title}
-`));
-          console.log(chalk.gray(nextStep.description));
-          console.log(chalk.gray(`
-Run 'paradigm tutorial step ${currentIndex + 2}' to view full instructions.
-`));
-        }
-      } else {
-        console.log(chalk.green("\n\u{1F389} Congratulations! You've completed all steps!\n"));
-        console.log(chalk.gray("Run 'paradigm tutorial next' to mark this step as complete.\n"));
-      }
-    } else {
-      console.log(chalk.red("\u274C Some checkpoints failed. Review the errors above.\n"));
-      process.exit(1);
-    }
-  } catch (error) {
-    console.error(chalk.red(`\u274C Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-async function tutorialNextCommand(targetPath) {
-  const rootDir = targetPath ? path.resolve(targetPath) : process.cwd();
-  try {
-    const curriculum = loadCurriculum(rootDir);
-    const state = loadState(rootDir);
-    if (!state.currentStep) {
-      console.log(chalk.yellow("\u26A0\uFE0F  No active step. Run `paradigm tutorial start` first."));
-      return;
-    }
-    const passed = await validateCheckpoint(rootDir, state.currentStep, curriculum);
-    if (!passed) {
-      console.log(chalk.red("\n\u274C Cannot proceed. Please complete current step checkpoints first.\n"));
-      process.exit(1);
-    }
-    if (!state.completedSteps.includes(state.currentStep)) {
-      state.completedSteps.push(state.currentStep);
-    }
-    const currentIndex = curriculum.steps.findIndex((s) => s.id === state.currentStep);
-    if (currentIndex < curriculum.steps.length - 1) {
-      state.currentStep = curriculum.steps[currentIndex + 1].id;
-      saveState(rootDir, state);
-      console.log(chalk.green(`
-\u2705 Step completed! Moving to next step.
-`));
-      await tutorialStepCommand(targetPath, String(currentIndex + 2));
-    } else {
-      state.currentStep = null;
-      saveState(rootDir, state);
-      console.log(chalk.green("\n\u{1F389} Congratulations! You've completed the tutorial!\n"));
-    }
-  } catch (error) {
-    console.error(chalk.red(`\u274C Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-async function tutorialStatusCommand(targetPath) {
-  const rootDir = targetPath ? path.resolve(targetPath) : process.cwd();
-  try {
-    const curriculum = loadCurriculum(rootDir);
-    const state = loadState(rootDir);
-    console.log(chalk.blue("\n\u{1F4CA} Tutorial Progress\n"));
-    console.log(`Current Step: ${state.currentStep || "Not started"}`);
-    console.log(`Completed: ${state.completedSteps.length}/${curriculum.steps.length}`);
-    console.log(`Bugs Fixed: ${state.fixedBugs.length}
-`);
-    if (state.currentStep) {
-      const step = curriculum.steps.find((s) => s.id === state.currentStep);
-      if (step) {
-        console.log(chalk.cyan(`Current: ${step.title}`));
-        console.log(chalk.gray(step.description));
-      }
-    }
-    console.log("");
-  } catch (error) {
-    console.error(chalk.red(`\u274C Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-async function tutorialResetCommand(targetPath) {
-  const rootDir = targetPath ? path.resolve(targetPath) : process.cwd();
-  const statePath = path.join(rootDir, TUTORIAL_STATE_FILE);
-  if (fs.existsSync(statePath)) {
-    fs.unlinkSync(statePath);
-  }
-  console.log(chalk.green("\n\u2705 Tutorial reset. Run `paradigm tutorial start` to begin again.\n"));
-}
-async function tutorialBugsCommand(targetPath) {
-  const rootDir = targetPath ? path.resolve(targetPath) : process.cwd();
-  try {
-    const curriculum = loadCurriculum(rootDir);
-    const state = loadState(rootDir);
-    console.log(chalk.blue("\n\u{1F41B} Intentional Bugs\n"));
-    for (const bug of curriculum.bugs || []) {
-      const fixed = state.fixedBugs.includes(bug.id);
-      console.log(`${fixed ? chalk.green("\u2705") : chalk.yellow("\u23F3")} ${bug.title}`);
-      console.log(chalk.gray(`   ${bug.description}`));
-      if (bug.hint) {
-        console.log(chalk.gray(`   Hint: ${bug.hint}`));
-      }
-      console.log("");
-    }
-  } catch (error) {
-    console.error(chalk.red(`\u274C Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-export {
-  tutorialBugsCommand,
-  tutorialCheckpointCommand,
-  tutorialNextCommand,
-  tutorialResetCommand,
-  tutorialStartCommand,
-  tutorialStatusCommand,
-  tutorialStepCommand
-};