@elysiumoss/grepo 0.2.0

package/lib/prompts/readme.js

@@ -0,0 +1,345 @@
+import { Logger as Logger$1 } from "../utils/logger.js";
+import { Schema } from "effect";
+//#region src/prompts/readme.ts
+/**
+*
+* Copyright 2026 Mike Odnis
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*
+*/
+const DiagramSchema = Schema.Struct({
+	keyNodes: Schema.Array(Schema.String),
+	purpose: Schema.String,
+	scope: Schema.String,
+	type: Schema.Literal("c4-context", "er", "flowchart", "sequence", "state")
+});
+const ExistingReadmeSchema = Schema.Struct({
+	improve: Schema.Array(Schema.String),
+	missing: Schema.Array(Schema.String),
+	preserve: Schema.Array(Schema.String),
+	quality: Schema.Literal("decent", "good", "none", "poor")
+});
+const IdentitySchema = Schema.Struct({
+	differentiators: Schema.Array(Schema.String),
+	name: Schema.String,
+	oneLiner: Schema.String
+});
+const SectionsSchema = Schema.Struct({
+	recommended: Schema.Array(Schema.String),
+	skip: Schema.Array(Schema.Struct({
+		reason: Schema.String,
+		section: Schema.String
+	}))
+});
+const ToneSchema = Schema.Literal("casual", "minimal", "professional", "technical");
+const ToneDetectionSchema = Schema.Struct({
+	detected: ToneSchema,
+	evidence: Schema.String
+});
+const AnalysisResult = Schema.Struct({
+	diagrams: Schema.Array(DiagramSchema),
+	existingReadme: ExistingReadmeSchema,
+	identity: IdentitySchema,
+	repoType: Schema.String,
+	sections: SectionsSchema,
+	tone: ToneDetectionSchema
+});
+const GenerationOptions = Schema.Struct({
+	format: Schema.Literal("md", "mdx"),
+	style: Schema.Literal("minimal", "standard", "comprehensive"),
+	tone: Schema.optional(ToneSchema)
+});
+const RepoData = Schema.Struct({
+	content: Schema.String,
+	repo_url: Schema.String,
+	summary: Schema.String,
+	tree: Schema.String
+});
+const DEFAULT_ANALYSIS = {
+	diagrams: [],
+	existingReadme: {
+		improve: [],
+		missing: [],
+		preserve: [],
+		quality: "none"
+	},
+	identity: {
+		differentiators: [],
+		name: "Unknown",
+		oneLiner: ""
+	},
+	repoType: "library",
+	sections: {
+		recommended: [
+			"hero",
+			"overview",
+			"installation",
+			"quick-start",
+			"usage",
+			"development",
+			"license"
+		],
+		skip: []
+	},
+	tone: {
+		detected: "professional",
+		evidence: "fallback default"
+	}
+};
+function extractExistingReadme(content) {
+	const readmeMatch = /(?:^|\n)(?:={3,}|─{3,})?\s*README\.md\s*(?:={3,}|─{3,})?\n([\s\S]*?)(?=\n(?:={3,}|─{3,})\s*\S+\.\S+|$)/.exec(content);
+	if (readmeMatch?.[1] && readmeMatch[1].trim().length > 50) return readmeMatch[1].trim();
+	return null;
+}
+function parseAnalysis(raw) {
+	try {
+		const stripped = raw.replace(/^```(?:json)?\s*/i, "").replace(/\s*```\s*$/, "").trim();
+		const json = JSON.parse(stripped);
+		const result = Schema.decodeUnknownSync(AnalysisResult)(json);
+		if (!result.sections.recommended.length) throw new Error("sections.recommended must not be empty");
+		return result;
+	} catch (err) {
+		new Logger$1("GREPO:README-PROMPT").warn(`Failed to parse analysis JSON, falling back to DEFAULT_ANALYSIS. Error: ${err instanceof Error ? err.message : String(err)}`);
+		return DEFAULT_ANALYSIS;
+	}
+}
+function buildAnalysisPrompt(repoData, existingReadme) {
+	const existingReadmeBlock = existingReadme ? `
+<existing_readme>
+${existingReadme.slice(0, 4e3)}
+</existing_readme>` : "";
+	return `You are an expert technical analyst. Analyze the repository below and return ONLY valid JSON — no markdown fences, no commentary, no extra text.
+
+<output_schema>
+{
+  "repoType": "string — e.g. cli-tool, library, web-app, api, monorepo, config, data-pipeline, etc.",
+  "identity": {
+    "name": "string — canonical project name",
+    "oneLiner": "string — one sentence describing what it does",
+    "differentiators": ["string — unique selling points"]
+  },
+  "tone": {
+    "detected": "casual | professional | minimal | technical",
+    "evidence": "string — quote or observation that led to this conclusion"
+  },
+  "sections": {
+    "recommended": ["string — section keys from the catalog below, in logical order"],
+    "skip": [{ "section": "string", "reason": "string" }]
+  },
+  "diagrams": [
+    {
+      "type": "flowchart | sequence | c4-context | er | state",
+      "purpose": "string — what this diagram explains",
+      "scope": "string — what subsystem or flow it covers",
+      "keyNodes": ["string — important nodes or actors"]
+    }
+  ],
+  "existingReadme": {
+    "quality": "good | decent | poor | none",
+    "preserve": ["string — sections or content worth keeping verbatim"],
+    "improve": ["string — sections that exist but need rework"],
+    "missing": ["string — important topics not covered"]
+  }
+}
+</output_schema>
+
+<section_catalog>
+hero           — project name, tagline, badges
+overview       — what it does and why it exists
+features       — bullet list of capabilities
+architecture   — system design, component overview
+installation   — how to install/setup
+quick-start    — minimal working example
+usage          — detailed usage instructions
+cli-reference  — CLI flags and subcommands
+api-reference  — public API docs
+configuration  — env vars, config files
+development    — local dev setup, contributing workflow
+deployment     — how to deploy/release
+contributing   — contribution guidelines
+license        — license info
+</section_catalog>
+
+<rules>
+- Only recommend sections that have real supporting content in the repository.
+- Recommend at most 2 diagrams. Choose diagram types based on:
+  - c4-context: multi-service architectures with external dependencies
+  - sequence: request/response workflows or multi-actor interactions
+  - flowchart: data pipelines, build processes, or decision trees
+  - state: object lifecycle or state machine logic
+  - er: data models with relationships
+- Detect tone from existing docs, comments, and README style (if present).
+- Be conservative: fewer well-chosen sections beat a bloated list.
+</rules>
+
+<repository_context>
+url: ${repoData.repo_url}
+summary: ${repoData.summary}
+
+<tree>
+${repoData.tree}
+</tree>
+
+<content>
+${repoData.content.slice(0, 8e3)}
+</content>
+</repository_context>
+${existingReadmeBlock}`;
+}
+const STYLE_GUIDANCE = {
+	comprehensive: "Be thorough. Multiple examples, edge cases, full API surface. Expand every recommended section fully.",
+	minimal: "Keep it concise. Favor short sentences and small sections. Omit exhaustive examples. Badge count ≤ 3.",
+	standard: "Balance depth and brevity. One code example per major section. Moderate badge set. Include a quick-start."
+};
+function buildExistingReadmeInstructions(analysis) {
+	if (analysis.existingReadme.quality === "none") return "No existing README was found. Generate the document from scratch.";
+	const lines = [`Existing README quality: ${analysis.existingReadme.quality}.`];
+	if (analysis.existingReadme.preserve.length > 0) lines.push(`Preserve the following content verbatim where possible:\n${analysis.existingReadme.preserve.map((s) => `  - ${s}`).join("\n")}`);
+	if (analysis.existingReadme.improve.length > 0) lines.push(`Improve (rewrite/expand) these sections:\n${analysis.existingReadme.improve.map((s) => `  - ${s}`).join("\n")}`);
+	if (analysis.existingReadme.missing.length > 0) lines.push(`Add these missing topics:\n${analysis.existingReadme.missing.map((s) => `  - ${s}`).join("\n")}`);
+	return lines.join("\n");
+}
+function buildGenerationPrompt(analysis, repoData, options) {
+	const effectiveTone = options.tone ?? analysis.tone.detected;
+	return `You are a senior technical writer generating a README for a software project.
+
+<output_rules>
+- Output ONLY the raw ${options.format.toUpperCase()} content. No preamble, no explanation, no markdown fences wrapping the whole document.
+- Only generate the sections listed in recommended_sections below. Do not add extras.
+- No generic filler phrases like "In this section we will…" or "This project is a…".
+- Mermaid diagrams must follow diagram_rules exactly.
+</output_rules>
+
+<analysis>
+${JSON.stringify(analysis, null, 2)}
+</analysis>
+
+<recommended_sections>
+${analysis.sections.recommended.join(", ")}
+</recommended_sections>
+
+<tone>
+Style: ${effectiveTone}
+Description: ${{
+		casual: "Friendly, approachable, first-person plural ('we'). Use contractions. Short paragraphs. Light humor is fine.",
+		minimal: "Extremely terse. Bullet points over prose. No introductory fluff. Every word must earn its place.",
+		professional: "Clear, precise, authoritative. Third-person or imperative. No jargon without definition. Avoid filler words.",
+		technical: "Assume a developer audience. Use correct terminology. Include type signatures, flags, and internals where relevant."
+	}[effectiveTone]}
+</tone>
+
+<diagram_rules>
+CRITICAL SYNTAX RULES (violations cause render errors):
+- Wrap ALL node labels in quotes if they contain spaces, special chars, or parentheses: A["My Label"]
+- NEVER use bare parentheses in labels — use quotes: A["Deploy (prod)"] NOT A[Deploy (prod)]
+- NEVER use colons in labels without quotes: A["Step: Init"] NOT A[Step: Init]
+- Arrow syntax: use --> for solid, -.-> for dotted. NEVER use -> alone in flowcharts.
+- Subgraph IDs must not contain spaces: subgraph auth_flow["Auth Flow"]
+- Semicolons are NOT terminators — do not end lines with ;
+- Each node definition must be on its own line.
+
+STYLE RULES:
+- Use descriptive labels on all nodes — never single letters like A, B, C.
+- Add meaningful labels on edges to describe data flow or actions.
+- Use subgraphs to group related nodes into logical clusters.
+- Limit diagrams to 15 nodes maximum.
+
+TYPE-SPECIFIC TEMPLATES (follow these exactly):
+
+flowchart (always TD):
+\`\`\`mermaid
+flowchart TD
+    A["User Request"] --> B{"Auth Valid?"}
+    B -->|Yes| C["Process Request"]
+    B -->|No| D["Return 401"]
+    C --> E["Send Response"]
+\`\`\`
+
+sequence:
+\`\`\`mermaid
+sequenceDiagram
+    actor User
+    participant API
+    participant DB
+    User->>API: POST /login
+    activate API
+    API->>DB: Query user
+    DB-->>API: User record
+    API-->>User: JWT token
+    deactivate API
+\`\`\`
+
+c4-context (use C4Context):
+\`\`\`mermaid
+C4Context
+    Person(user, "Developer", "Uses the CLI tool")
+    System(cli, "CLI", "Command-line interface")
+    System_Ext(api, "GitHub API", "Repository management")
+    Rel(user, cli, "Runs commands")
+    Rel(cli, api, "REST calls")
+\`\`\`
+
+er:
+\`\`\`mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||--o{ LINE_ITEM : "ordered in"
+\`\`\`
+
+state:
+\`\`\`mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Processing : start
+    Processing --> Done : complete
+    Processing --> Failed : error
+    Failed --> Idle : retry
+    Done --> [*]
+\`\`\`
+
+COMMON MISTAKES TO AVOID:
+- Using "graph" instead of "flowchart"
+- Missing quotes around labels with special characters
+- Using C4_Context instead of C4Context
+- Forgetting "activate/deactivate" in sequence diagrams
+- Using --> in sequence diagrams (use ->> or -->> instead)
+</diagram_rules>
+
+<existing_readme_handling>
+${buildExistingReadmeInstructions(analysis)}
+</existing_readme_handling>
+
+<style_profile>
+Documentation style: ${options.style}
+${STYLE_GUIDANCE[options.style]}
+</style_profile>
+
+<repository_context>
+url: ${repoData.repo_url}
+summary: ${repoData.summary}
+
+<tree>
+${repoData.tree}
+</tree>
+
+<content>
+${repoData.content}
+</content>
+</repository_context>`;
+}
+//#endregion
+export { AnalysisResult, DEFAULT_ANALYSIS, DiagramSchema, ExistingReadmeSchema, GenerationOptions, IdentitySchema, RepoData, STYLE_GUIDANCE, SectionsSchema, ToneDetectionSchema, ToneSchema, buildAnalysisPrompt, buildExistingReadmeInstructions, buildGenerationPrompt, extractExistingReadme, parseAnalysis };
+
+//# sourceMappingURL=readme.js.map

package/lib/prompts/readme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme.js","names":["Logger"],"sources":["../../src/prompts/readme.ts"],"sourcesContent":["/**\n *\n * Copyright 2026 Mike Odnis\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n *\n */\n\nimport { Schema } from \"effect\";\n\nimport type { DocumentationStyle } from \"../config.js\";\nimport { Logger } from \"../utils/logger.js\";\n\n// ============================================================================\n// Types & Schemas\n// ============================================================================\n\nexport const DiagramSchema = Schema.Struct({\n\tkeyNodes: Schema.Array(Schema.String),\n\tpurpose: Schema.String,\n\tscope: Schema.String,\n\ttype: Schema.Literal(\"c4-context\", \"er\", \"flowchart\", \"sequence\", \"state\"),\n});\n\nexport const ExistingReadmeSchema = Schema.Struct({\n\timprove: Schema.Array(Schema.String),\n\tmissing: Schema.Array(Schema.String),\n\tpreserve: Schema.Array(Schema.String),\n\tquality: Schema.Literal(\"decent\", \"good\", \"none\", \"poor\"),\n});\n\nexport const IdentitySchema = Schema.Struct({\n\tdifferentiators: Schema.Array(Schema.String),\n\tname: Schema.String,\n\toneLiner: Schema.String,\n});\n\nexport const SectionsSchema = Schema.Struct({\n\trecommended: Schema.Array(Schema.String),\n\tskip: Schema.Array(\n\t\tSchema.Struct({\n\t\t\treason: Schema.String,\n\t\t\tsection: Schema.String,\n\t\t}),\n\t),\n});\n\nexport const ToneSchema = Schema.Literal(\n\t\"casual\",\n\t\"minimal\",\n\t\"professional\",\n\t\"technical\",\n);\nexport type Tone = Schema.Schema.Type<typeof ToneSchema>;\n\nexport const ToneDetectionSchema = Schema.Struct({\n\tdetected: ToneSchema,\n\tevidence: Schema.String,\n});\n\nexport const AnalysisResult = Schema.Struct({\n\tdiagrams: Schema.Array(DiagramSchema),\n\texistingReadme: ExistingReadmeSchema,\n\tidentity: IdentitySchema,\n\trepoType: Schema.String,\n\tsections: SectionsSchema,\n\ttone: ToneDetectionSchema,\n});\nexport type AnalysisResult = Schema.Schema.Type<typeof AnalysisResult>;\n\nexport const GenerationOptions = Schema.Struct({\n\tformat: Schema.Literal(\"md\", \"mdx\"),\n\tstyle: Schema.Literal(\"minimal\", \"standard\", \"comprehensive\"),\n\ttone: Schema.optional(ToneSchema),\n});\nexport type GenerationOptions = Schema.Schema.Type<typeof GenerationOptions>;\n\n// ============================================================================\n// Repo Data Schema\n// ============================================================================\n\nexport const RepoData = Schema.Struct({\n\tcontent: Schema.String,\n\trepo_url: Schema.String,\n\tsummary: Schema.String,\n\ttree: Schema.String,\n});\nexport type RepoData = Schema.Schema.Type<typeof RepoData>;\n\n// ============================================================================\n// Default Fallback\n// ============================================================================\n\nexport const DEFAULT_ANALYSIS: AnalysisResult = {\n\tdiagrams: [],\n\texistingReadme: {\n\t\timprove: [],\n\t\tmissing: [],\n\t\tpreserve: [],\n\t\tquality: \"none\",\n\t},\n\tidentity: {\n\t\tdifferentiators: [],\n\t\tname: \"Unknown\",\n\t\toneLiner: \"\",\n\t},\n\trepoType: \"library\",\n\tsections: {\n\t\trecommended: [\n\t\t\t\"hero\",\n\t\t\t\"overview\",\n\t\t\t\"installation\",\n\t\t\t\"quick-start\",\n\t\t\t\"usage\",\n\t\t\t\"development\",\n\t\t\t\"license\",\n\t\t],\n\t\tskip: [],\n\t},\n\ttone: {\n\t\tdetected: \"professional\",\n\t\tevidence: \"fallback default\",\n\t},\n};\n\n// ============================================================================\n// Utilities\n// ============================================================================\n\nexport function extractExistingReadme(content: string): string | null {\n\tconst readmeMatch =\n\t\t/(?:^|\\n)(?:={3,}|─{3,})?\\s*README\\.md\\s*(?:={3,}|─{3,})?\\n([\\s\\S]*?)(?=\\n(?:={3,}|─{3,})\\s*\\S+\\.\\S+|$)/.exec(\n\t\t\tcontent,\n\t\t);\n\tif (readmeMatch?.[1] && readmeMatch[1].trim().length > 50) {\n\t\treturn readmeMatch[1].trim();\n\t}\n\treturn null;\n}\n\nexport function parseAnalysis(raw: string): AnalysisResult {\n\ttry {\n\t\tconst stripped = raw\n\t\t\t.replace(/^```(?:json)?\\s*/i, \"\")\n\t\t\t.replace(/\\s*```\\s*$/, \"\")\n\t\t\t.trim();\n\n\t\tconst json = JSON.parse(stripped) as unknown;\n\t\tconst result = Schema.decodeUnknownSync(AnalysisResult)(json);\n\n\t\tif (!result.sections.recommended.length) {\n\t\t\tthrow new Error(\"sections.recommended must not be empty\");\n\t\t}\n\n\t\treturn result;\n\t} catch (err) {\n\t\tconst logger = new Logger(\"GREPO:README-PROMPT\");\n\t\tlogger.warn(\n\t\t\t`Failed to parse analysis JSON, falling back to DEFAULT_ANALYSIS. Error: ${\n\t\t\t\terr instanceof Error ? err.message : String(err)\n\t\t\t}`,\n\t\t);\n\t\treturn DEFAULT_ANALYSIS;\n\t}\n}\n\n// ============================================================================\n// Phase 1: Analysis Prompt\n// ============================================================================\n\nexport function buildAnalysisPrompt(\n\trepoData: RepoData,\n\texistingReadme?: string,\n): string {\n\tconst existingReadmeBlock = existingReadme\n\t\t? `\n<existing_readme>\n${existingReadme.slice(0, 4000)}\n</existing_readme>`\n\t\t: \"\";\n\n\treturn `You are an expert technical analyst. Analyze the repository below and return ONLY valid JSON — no markdown fences, no commentary, no extra text.\n\n<output_schema>\n{\n  \"repoType\": \"string — e.g. cli-tool, library, web-app, api, monorepo, config, data-pipeline, etc.\",\n  \"identity\": {\n    \"name\": \"string — canonical project name\",\n    \"oneLiner\": \"string — one sentence describing what it does\",\n    \"differentiators\": [\"string — unique selling points\"]\n  },\n  \"tone\": {\n    \"detected\": \"casual | professional | minimal | technical\",\n    \"evidence\": \"string — quote or observation that led to this conclusion\"\n  },\n  \"sections\": {\n    \"recommended\": [\"string — section keys from the catalog below, in logical order\"],\n    \"skip\": [{ \"section\": \"string\", \"reason\": \"string\" }]\n  },\n  \"diagrams\": [\n    {\n      \"type\": \"flowchart | sequence | c4-context | er | state\",\n      \"purpose\": \"string — what this diagram explains\",\n      \"scope\": \"string — what subsystem or flow it covers\",\n      \"keyNodes\": [\"string — important nodes or actors\"]\n    }\n  ],\n  \"existingReadme\": {\n    \"quality\": \"good | decent | poor | none\",\n    \"preserve\": [\"string — sections or content worth keeping verbatim\"],\n    \"improve\": [\"string — sections that exist but need rework\"],\n    \"missing\": [\"string — important topics not covered\"]\n  }\n}\n</output_schema>\n\n<section_catalog>\nhero           — project name, tagline, badges\noverview       — what it does and why it exists\nfeatures       — bullet list of capabilities\narchitecture   — system design, component overview\ninstallation   — how to install/setup\nquick-start    — minimal working example\nusage          — detailed usage instructions\ncli-reference  — CLI flags and subcommands\napi-reference  — public API docs\nconfiguration  — env vars, config files\ndevelopment    — local dev setup, contributing workflow\ndeployment     — how to deploy/release\ncontributing   — contribution guidelines\nlicense        — license info\n</section_catalog>\n\n<rules>\n- Only recommend sections that have real supporting content in the repository.\n- Recommend at most 2 diagrams. Choose diagram types based on:\n  - c4-context: multi-service architectures with external dependencies\n  - sequence: request/response workflows or multi-actor interactions\n  - flowchart: data pipelines, build processes, or decision trees\n  - state: object lifecycle or state machine logic\n  - er: data models with relationships\n- Detect tone from existing docs, comments, and README style (if present).\n- Be conservative: fewer well-chosen sections beat a bloated list.\n</rules>\n\n<repository_context>\nurl: ${repoData.repo_url}\nsummary: ${repoData.summary}\n\n<tree>\n${repoData.tree}\n</tree>\n\n<content>\n${repoData.content.slice(0, 8000)}\n</content>\n</repository_context>\n${existingReadmeBlock}`;\n}\n\n// ============================================================================\n// Phase 2: Generation Helpers\n// ============================================================================\n\nexport const STYLE_GUIDANCE: Record<DocumentationStyle, string> = {\n\tcomprehensive:\n\t\t\"Be thorough. Multiple examples, edge cases, full API surface. Expand every recommended section fully.\",\n\tminimal:\n\t\t\"Keep it concise. Favor short sentences and small sections. Omit exhaustive examples. Badge count ≤ 3.\",\n\tstandard:\n\t\t\"Balance depth and brevity. One code example per major section. Moderate badge set. Include a quick-start.\",\n};\n\nexport function buildExistingReadmeInstructions(\n\tanalysis: AnalysisResult,\n): string {\n\tif (analysis.existingReadme.quality === \"none\") {\n\t\treturn \"No existing README was found. Generate the document from scratch.\";\n\t}\n\n\tconst lines: string[] = [\n\t\t`Existing README quality: ${analysis.existingReadme.quality}.`,\n\t];\n\n\tif (analysis.existingReadme.preserve.length > 0) {\n\t\tlines.push(\n\t\t\t`Preserve the following content verbatim where possible:\\n${analysis.existingReadme.preserve.map((s) => `  - ${s}`).join(\"\\n\")}`,\n\t\t);\n\t}\n\n\tif (analysis.existingReadme.improve.length > 0) {\n\t\tlines.push(\n\t\t\t`Improve (rewrite/expand) these sections:\\n${analysis.existingReadme.improve.map((s) => `  - ${s}`).join(\"\\n\")}`,\n\t\t);\n\t}\n\n\tif (analysis.existingReadme.missing.length > 0) {\n\t\tlines.push(\n\t\t\t`Add these missing topics:\\n${analysis.existingReadme.missing.map((s) => `  - ${s}`).join(\"\\n\")}`,\n\t\t);\n\t}\n\n\treturn lines.join(\"\\n\");\n}\n\n// ============================================================================\n// Phase 2: Generation Prompt\n// ============================================================================\n\nexport function buildGenerationPrompt(\n\tanalysis: AnalysisResult,\n\trepoData: RepoData,\n\toptions: GenerationOptions,\n): string {\n\tconst effectiveTone: Tone = options.tone ?? analysis.tone.detected;\n\n\tconst toneDescriptions: Record<Tone, string> = {\n\t\tcasual:\n\t\t\t\"Friendly, approachable, first-person plural ('we'). Use contractions. Short paragraphs. Light humor is fine.\",\n\t\tminimal:\n\t\t\t\"Extremely terse. Bullet points over prose. No introductory fluff. Every word must earn its place.\",\n\t\tprofessional:\n\t\t\t\"Clear, precise, authoritative. Third-person or imperative. No jargon without definition. Avoid filler words.\",\n\t\ttechnical:\n\t\t\t\"Assume a developer audience. Use correct terminology. Include type signatures, flags, and internals where relevant.\",\n\t};\n\n\treturn `You are a senior technical writer generating a README for a software project.\n\n<output_rules>\n- Output ONLY the raw ${options.format.toUpperCase()} content. No preamble, no explanation, no markdown fences wrapping the whole document.\n- Only generate the sections listed in recommended_sections below. Do not add extras.\n- No generic filler phrases like \"In this section we will…\" or \"This project is a…\".\n- Mermaid diagrams must follow diagram_rules exactly.\n</output_rules>\n\n<analysis>\n${JSON.stringify(analysis, null, 2)}\n</analysis>\n\n<recommended_sections>\n${analysis.sections.recommended.join(\", \")}\n</recommended_sections>\n\n<tone>\nStyle: ${effectiveTone}\nDescription: ${toneDescriptions[effectiveTone]}\n</tone>\n\n<diagram_rules>\nCRITICAL SYNTAX RULES (violations cause render errors):\n- Wrap ALL node labels in quotes if they contain spaces, special chars, or parentheses: A[\"My Label\"]\n- NEVER use bare parentheses in labels — use quotes: A[\"Deploy (prod)\"] NOT A[Deploy (prod)]\n- NEVER use colons in labels without quotes: A[\"Step: Init\"] NOT A[Step: Init]\n- Arrow syntax: use --> for solid, -.-> for dotted. NEVER use -> alone in flowcharts.\n- Subgraph IDs must not contain spaces: subgraph auth_flow[\"Auth Flow\"]\n- Semicolons are NOT terminators — do not end lines with ;\n- Each node definition must be on its own line.\n\nSTYLE RULES:\n- Use descriptive labels on all nodes — never single letters like A, B, C.\n- Add meaningful labels on edges to describe data flow or actions.\n- Use subgraphs to group related nodes into logical clusters.\n- Limit diagrams to 15 nodes maximum.\n\nTYPE-SPECIFIC TEMPLATES (follow these exactly):\n\nflowchart (always TD):\n\\`\\`\\`mermaid\nflowchart TD\n    A[\"User Request\"] --> B{\"Auth Valid?\"}\n    B -->|Yes| C[\"Process Request\"]\n    B -->|No| D[\"Return 401\"]\n    C --> E[\"Send Response\"]\n\\`\\`\\`\n\nsequence:\n\\`\\`\\`mermaid\nsequenceDiagram\n    actor User\n    participant API\n    participant DB\n    User->>API: POST /login\n    activate API\n    API->>DB: Query user\n    DB-->>API: User record\n    API-->>User: JWT token\n    deactivate API\n\\`\\`\\`\n\nc4-context (use C4Context):\n\\`\\`\\`mermaid\nC4Context\n    Person(user, \"Developer\", \"Uses the CLI tool\")\n    System(cli, \"CLI\", \"Command-line interface\")\n    System_Ext(api, \"GitHub API\", \"Repository management\")\n    Rel(user, cli, \"Runs commands\")\n    Rel(cli, api, \"REST calls\")\n\\`\\`\\`\n\ner:\n\\`\\`\\`mermaid\nerDiagram\n    USER ||--o{ ORDER : places\n    ORDER ||--|{ LINE_ITEM : contains\n    PRODUCT ||--o{ LINE_ITEM : \"ordered in\"\n\\`\\`\\`\n\nstate:\n\\`\\`\\`mermaid\nstateDiagram-v2\n    [*] --> Idle\n    Idle --> Processing : start\n    Processing --> Done : complete\n    Processing --> Failed : error\n    Failed --> Idle : retry\n    Done --> [*]\n\\`\\`\\`\n\nCOMMON MISTAKES TO AVOID:\n- Using \"graph\" instead of \"flowchart\"\n- Missing quotes around labels with special characters\n- Using C4_Context instead of C4Context\n- Forgetting \"activate/deactivate\" in sequence diagrams\n- Using --> in sequence diagrams (use ->> or -->> instead)\n</diagram_rules>\n\n<existing_readme_handling>\n${buildExistingReadmeInstructions(analysis)}\n</existing_readme_handling>\n\n<style_profile>\nDocumentation style: ${options.style}\n${STYLE_GUIDANCE[options.style]}\n</style_profile>\n\n<repository_context>\nurl: ${repoData.repo_url}\nsummary: ${repoData.summary}\n\n<tree>\n${repoData.tree}\n</tree>\n\n<content>\n${repoData.content}\n</content>\n</repository_context>`;\n}\n"],"mappings":"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"}

package/lib/services.d.ts

@@ -0,0 +1,29 @@
+import { GeminiError, GitHubError, GitIngestError } from "./errors.js";
+import { GitIngestResponse } from "./utils/gitingest.js";
+import { Context, Effect, Layer, Schema } from "effect";
+
+//#region src/services.d.ts
+
+interface GeminiServiceApi {
+  readonly generateContent: (prompt: string) => Effect.Effect<string, GeminiError>;
+}
+declare const Gemini_base: Context.TagClass<Gemini, "Gemini", GeminiServiceApi>;
+declare class Gemini extends Gemini_base {}
+declare const GeminiLive: (apiKey: string) => Layer.Layer<Gemini, never, never>;
+interface GitHubServiceApi {
+  readonly getTopics: (owner: string, repo: string) => Effect.Effect<readonly string[], GitHubError>;
+  readonly pushFile: (owner: string, repo: string, path: string, content: string, message: string, branch: string) => Effect.Effect<void, GitHubError>;
+  readonly setTopics: (owner: string, repo: string, topics: string[]) => Effect.Effect<void, GitHubError>;
+  readonly updateRepo: (owner: string, repo: string, data: {
+    description?: string;
+    homepage?: string;
+  }) => Effect.Effect<void, GitHubError>;
+}
+declare const GitHub_base: Context.TagClass<GitHub, "GitHub", GitHubServiceApi>;
+declare class GitHub extends GitHub_base {}
+declare const GitHubLive: (token?: string) => Layer.Layer<GitHub, never, never>;
+type RepoData = Schema.Schema.Type<typeof GitIngestResponse>;
+declare const fetchRepo: (repoUrl: string) => Effect.Effect<RepoData, GitIngestError>;
+//#endregion
+export { Gemini, GeminiLive, GeminiServiceApi, GitHub, GitHubLive, GitHubServiceApi, RepoData, fetchRepo };
+//# sourceMappingURL=services.d.ts.map

package/lib/services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.d.ts","names":[],"sources":["../src/services.ts"],"sourcesContent":[],"mappings":";;;;;;AAgFM,UA/CW,gBAAA,CA+CJ;EAAM,SAAA,eAAA,EAAA,CAAA,MAAA,EAAA,MAAA,EAAA,GA5Cb,MAAA,CAAO,MA4CM,CAAA,MAAA,EA5CS,WA4CT,CAAA;AAClB;cA5CA;cAEY,MAAA,SAAe,WAAA;cAEf,gCAA4B,KAAA,CAAA,MAAA;AA0C5B,UAzBI,gBAAA,CAyBW;EAEf,SAAA,SAwCZ,EAAA,CAAA,KAxCwC,EAAA,MAAA,EAAA,IAAA,EAAA,MAAA,EAAA,GAvBnC,MAAA,CAAO,MAuB4B,CAAA,SAAA,MAAA,EAAA,EAvBF,WAuBE,CAAA;EA8C7B,SAAA,QAAQ,EAAA,CAAA,KAA6B,EAAA,MAAA,EAAA,IAAA,EAAA,MAA1B,EAAO,IAAA,EAAA,MAAW,EAAA,OAAA,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,EAAA,MAAA,EAAA,MAAA,EAAA,GA7DnC,MAAA,CAAO,MA6D4B,CAAA,IAAA,EA7Df,WA6De,CAAA;EAE5B,SAAA,SAUV,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,IAAA,EAAA,MAAA,EAAA,MAAA,EAAA,MAAA,EAAA,EAAA,GApEG,MAAA,CAAO,MAoEV,CAAA,IAAA,EApEuB,WAoEvB,CAAA;EARc,SAAA,UAAA,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,IAAA,EAAA,MAAA,EAAA,IAAA,EAAA;IAAU,WAAA,CAAA,EAAA,MAAA;IAAjB,QAAA,CAAA,EAAA,MAAA;EAAM,CAAA,EAAA,GAvDV,MAAA,CAAO,MAuDG,CAAA,IAAA,EAvDU,WAuDV,CAAA;;cAtDf;cAEY,MAAA,SAAe,WAAA;cAEf,gCAA4B,KAAA,CAAA,MAAA;KA8C7B,QAAA,GAAW,MAAA,CAAO,MAAA,CAAO,YAAY;cAEpC,gCAEV,MAAA,CAAO,OAAO,UAAU"}

package/lib/services.js

@@ -0,0 +1,59 @@
+import { GeminiError, GitHubError, GitIngestError } from "./errors.js";
+import { GeminiService } from "./utils/gemini.js";
+import { GitHubClient } from "./utils/github.js";
+import { fetchRepositoryContent } from "./utils/gitingest.js";
+import { Context, Effect, Layer } from "effect";
+//#region src/services.ts
+var Gemini = class extends Context.Tag("Gemini")() {};
+const GeminiLive = (apiKey) => Layer.succeed(Gemini, { generateContent: (prompt) => Effect.tryPromise({
+	catch: (error) => new GeminiError({
+		cause: error,
+		message: error instanceof Error ? error.message : String(error)
+	}),
+	try: () => new GeminiService(apiKey).generateContent(prompt)
+}) });
+var GitHub = class extends Context.Tag("GitHub")() {};
+const GitHubLive = (token) => {
+	const client = new GitHubClient(token);
+	return Layer.succeed(GitHub, {
+		getTopics: (owner, repo) => Effect.tryPromise({
+			catch: (error) => new GitHubError({
+				endpoint: `repos/${owner}/${repo}/topics`,
+				message: error instanceof Error ? error.message : String(error)
+			}),
+			try: () => client.getTopics(owner, repo)
+		}),
+		pushFile: (owner, repo, path, content, message, branch) => Effect.tryPromise({
+			catch: (error) => new GitHubError({
+				endpoint: `repos/${owner}/${repo}/contents/${path}`,
+				message: error instanceof Error ? error.message : String(error)
+			}),
+			try: () => client.pushFile(owner, repo, path, content, message, branch)
+		}),
+		setTopics: (owner, repo, topics) => Effect.tryPromise({
+			catch: (error) => new GitHubError({
+				endpoint: `repos/${owner}/${repo}/topics`,
+				message: error instanceof Error ? error.message : String(error)
+			}),
+			try: () => client.setTopics(owner, repo, topics)
+		}),
+		updateRepo: (owner, repo, data) => Effect.tryPromise({
+			catch: (error) => new GitHubError({
+				endpoint: `repos/${owner}/${repo}`,
+				message: error instanceof Error ? error.message : String(error)
+			}),
+			try: () => client.updateRepo(owner, repo, data)
+		})
+	});
+};
+const fetchRepo = (repoUrl) => Effect.tryPromise({
+	catch: (error) => new GitIngestError({
+		cause: error,
+		message: error instanceof Error ? error.message : String(error)
+	}),
+	try: () => fetchRepositoryContent(repoUrl)
+});
+//#endregion
+export { Gemini, GeminiLive, GitHub, GitHubLive, fetchRepo };
+
+//# sourceMappingURL=services.js.map

package/lib/services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.js","names":["GeminiClient"],"sources":["../src/services.ts"],"sourcesContent":["/**\n *\n * Copyright 2026 Mike Odnis\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n *\n */\n\nimport type { Schema } from \"effect\";\nimport { Context, Effect, Layer } from \"effect\";\n\nimport { GeminiError, GitHubError, GitIngestError } from \"./errors.js\";\nimport { GeminiService as GeminiClient } from \"./utils/gemini.js\";\nimport { GitHubClient } from \"./utils/github.js\";\nimport {\n\tfetchRepositoryContent,\n\ttype GitIngestResponse,\n} from \"./utils/gitingest.js\";\n\n// ============================================================================\n// Gemini Service\n// ============================================================================\n\nexport interface GeminiServiceApi {\n\treadonly generateContent: (\n\t\tprompt: string,\n\t) => Effect.Effect<string, GeminiError>;\n}\n\nexport class Gemini extends Context.Tag(\"Gemini\")<Gemini, GeminiServiceApi>() {}\n\nexport const GeminiLive = (apiKey: string) =>\n\tLayer.succeed(Gemini, {\n\t\tgenerateContent: (prompt: string) =>\n\t\t\tEffect.tryPromise({\n\t\t\t\tcatch: (error) =>\n\t\t\t\t\tnew GeminiError({\n\t\t\t\t\t\tcause: error,\n\t\t\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t\t\t}),\n\t\t\t\ttry: () => new GeminiClient(apiKey).generateContent(prompt),\n\t\t\t}),\n\t});\n\n// ============================================================================\n// GitHub Service\n// ============================================================================\n\nexport interface GitHubServiceApi {\n\treadonly getTopics: (\n\t\towner: string,\n\t\trepo: string,\n\t) => Effect.Effect<readonly string[], GitHubError>;\n\treadonly pushFile: (\n\t\towner: string,\n\t\trepo: string,\n\t\tpath: string,\n\t\tcontent: string,\n\t\tmessage: string,\n\t\tbranch: string,\n\t) => Effect.Effect<void, GitHubError>;\n\treadonly setTopics: (\n\t\towner: string,\n\t\trepo: string,\n\t\ttopics: string[],\n\t) => Effect.Effect<void, GitHubError>;\n\treadonly updateRepo: (\n\t\towner: string,\n\t\trepo: string,\n\t\tdata: { description?: string; homepage?: string },\n\t) => Effect.Effect<void, GitHubError>;\n}\n\nexport class GitHub extends Context.Tag(\"GitHub\")<GitHub, GitHubServiceApi>() {}\n\nexport const GitHubLive = (token?: string) => {\n\tconst client = new GitHubClient(token);\n\treturn Layer.succeed(GitHub, {\n\t\tgetTopics: (owner, repo) =>\n\t\t\tEffect.tryPromise({\n\t\t\t\tcatch: (error) =>\n\t\t\t\t\tnew GitHubError({\n\t\t\t\t\t\tendpoint: `repos/${owner}/${repo}/topics`,\n\t\t\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t\t\t}),\n\t\t\t\ttry: () => client.getTopics(owner, repo),\n\t\t\t}),\n\t\tpushFile: (owner, repo, path, content, message, branch) =>\n\t\t\tEffect.tryPromise({\n\t\t\t\tcatch: (error) =>\n\t\t\t\t\tnew GitHubError({\n\t\t\t\t\t\tendpoint: `repos/${owner}/${repo}/contents/${path}`,\n\t\t\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t\t\t}),\n\t\t\t\ttry: () => client.pushFile(owner, repo, path, content, message, branch),\n\t\t\t}),\n\t\tsetTopics: (owner, repo, topics) =>\n\t\t\tEffect.tryPromise({\n\t\t\t\tcatch: (error) =>\n\t\t\t\t\tnew GitHubError({\n\t\t\t\t\t\tendpoint: `repos/${owner}/${repo}/topics`,\n\t\t\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t\t\t}),\n\t\t\t\ttry: () => client.setTopics(owner, repo, topics),\n\t\t\t}),\n\t\tupdateRepo: (owner, repo, data) =>\n\t\t\tEffect.tryPromise({\n\t\t\t\tcatch: (error) =>\n\t\t\t\t\tnew GitHubError({\n\t\t\t\t\t\tendpoint: `repos/${owner}/${repo}`,\n\t\t\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t\t\t}),\n\t\t\t\ttry: () => client.updateRepo(owner, repo, data),\n\t\t\t}),\n\t});\n};\n\n// ============================================================================\n// GitIngest Service\n// ============================================================================\n\nexport type RepoData = Schema.Schema.Type<typeof GitIngestResponse>;\n\nexport const fetchRepo = (\n\trepoUrl: string,\n): Effect.Effect<RepoData, GitIngestError> =>\n\tEffect.tryPromise({\n\t\tcatch: (error) =>\n\t\t\tnew GitIngestError({\n\t\t\t\tcause: error,\n\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t}),\n\t\ttry: () => fetchRepositoryContent(repoUrl),\n\t});\n"],"mappings":";;;;;;AAuCA,IAAa,SAAb,cAA4B,QAAQ,IAAI,SAAS,EAA4B,CAAC;AAE9E,MAAa,cAAc,WAC1B,MAAM,QAAQ,QAAQ,EACrB,kBAAkB,WACjB,OAAO,WAAW;CACjB,QAAQ,UACP,IAAI,YAAY;EACf,OAAO;EACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;EAC/D,CAAC;CACH,WAAW,IAAIA,cAAa,OAAO,CAAC,gBAAgB,OAAO;CAC3D,CAAC,EACH,CAAC;AA+BH,IAAa,SAAb,cAA4B,QAAQ,IAAI,SAAS,EAA4B,CAAC;AAE9E,MAAa,cAAc,UAAmB;CAC7C,MAAM,SAAS,IAAI,aAAa,MAAM;AACtC,QAAO,MAAM,QAAQ,QAAQ;EAC5B,YAAY,OAAO,SAClB,OAAO,WAAW;GACjB,QAAQ,UACP,IAAI,YAAY;IACf,UAAU,SAAS,MAAM,GAAG,KAAK;IACjC,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;IAC/D,CAAC;GACH,WAAW,OAAO,UAAU,OAAO,KAAK;GACxC,CAAC;EACH,WAAW,OAAO,MAAM,MAAM,SAAS,SAAS,WAC/C,OAAO,WAAW;GACjB,QAAQ,UACP,IAAI,YAAY;IACf,UAAU,SAAS,MAAM,GAAG,KAAK,YAAY;IAC7C,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;IAC/D,CAAC;GACH,WAAW,OAAO,SAAS,OAAO,MAAM,MAAM,SAAS,SAAS,OAAO;GACvE,CAAC;EACH,YAAY,OAAO,MAAM,WACxB,OAAO,WAAW;GACjB,QAAQ,UACP,IAAI,YAAY;IACf,UAAU,SAAS,MAAM,GAAG,KAAK;IACjC,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;IAC/D,CAAC;GACH,WAAW,OAAO,UAAU,OAAO,MAAM,OAAO;GAChD,CAAC;EACH,aAAa,OAAO,MAAM,SACzB,OAAO,WAAW;GACjB,QAAQ,UACP,IAAI,YAAY;IACf,UAAU,SAAS,MAAM,GAAG;IAC5B,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;IAC/D,CAAC;GACH,WAAW,OAAO,WAAW,OAAO,MAAM,KAAK;GAC/C,CAAC;EACH,CAAC;;AASH,MAAa,aACZ,YAEA,OAAO,WAAW;CACjB,QAAQ,UACP,IAAI,eAAe;EAClB,OAAO;EACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;EAC/D,CAAC;CACH,WAAW,uBAAuB,QAAQ;CAC1C,CAAC"}

package/lib/utils/args.d.ts

@@ -0,0 +1,15 @@
+import { Schema } from "effect";
+
+//#region src/utils/args.d.ts
+
+declare const ParsedArgs: Schema.Struct<{
+  options: Schema.Record$<typeof Schema.String, Schema.Union<[typeof Schema.String, typeof Schema.Boolean]>>;
+  positional: Schema.Array$<typeof Schema.String>;
+}>;
+type ParsedArgs = Schema.Schema.Type<typeof ParsedArgs>;
+declare function parseArgs(args: string[], booleanFlags?: string[]): ParsedArgs;
+declare const SEPARATOR: string;
+declare function displayHeader(title: string, details: Record<string, string>): void;
+//#endregion
+export { ParsedArgs, SEPARATOR, displayHeader, parseArgs };
+//# sourceMappingURL=args.d.ts.map

package/lib/utils/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","names":[],"sources":["../../src/utils/args.ts"],"sourcesContent":[],"mappings":";;;;cAoBM,YAAU,MAAA,CAAA;;;;KAQJ,UAAA,GAAa,MAAA,CAAO,MAAA,CAAO,YAAY;iBAEnC,SAAA,2CAGb;cAyCU;iBAEG,aAAA,yBAEN"}

package/lib/utils/args.js

@@ -0,0 +1,70 @@
+import { Schema } from "effect";
+//#region src/utils/args.ts
+/**
+*
+* Copyright 2026 Mike Odnis
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*
+*/
+Schema.Struct({
+	options: Schema.Record({
+		key: Schema.String,
+		value: Schema.Union(Schema.String, Schema.Boolean)
+	}),
+	positional: Schema.Array(Schema.String)
+});
+function parseArgs(args, booleanFlags = []) {
+	const positional = [];
+	const options = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (!arg) continue;
+		if (arg.startsWith("--")) {
+			const longArg = arg.slice(2);
+			if (longArg.includes("=")) {
+				const [key, ...valueParts] = longArg.split("=");
+				if (key) options[key] = valueParts.join("=");
+				continue;
+			}
+			const key = longArg;
+			const nextArg = args[i + 1];
+			if (booleanFlags.includes(key)) {
+				options[key] = true;
+				continue;
+			}
+			if (nextArg && !nextArg.startsWith("--")) {
+				options[key] = nextArg;
+				i++;
+			} else options[key] = true;
+		} else positional.push(arg);
+	}
+	return {
+		options,
+		positional
+	};
+}
+const SEPARATOR = "=".repeat(80);
+function displayHeader(title, details) {
+	console.log();
+	console.log(SEPARATOR);
+	console.log(`  🚀 ${title}`);
+	console.log(SEPARATOR);
+	for (const [key, value] of Object.entries(details)) console.log(`  • ${key}: ${value}`);
+	console.log(SEPARATOR);
+	console.log();
+}
+//#endregion
+export { SEPARATOR, displayHeader, parseArgs };
+
+//# sourceMappingURL=args.js.map

package/lib/utils/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","names":[],"sources":["../../src/utils/args.ts"],"sourcesContent":["/**\n *\n * Copyright 2026 Mike Odnis\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n *\n */\n\nimport { Schema } from \"effect\";\n\nconst ParsedArgs = Schema.Struct({\n\toptions: Schema.Record({\n\t\tkey: Schema.String,\n\t\tvalue: Schema.Union(Schema.String, Schema.Boolean),\n\t}),\n\tpositional: Schema.Array(Schema.String),\n});\n\nexport type ParsedArgs = Schema.Schema.Type<typeof ParsedArgs>;\n\nexport function parseArgs(\n\targs: string[],\n\tbooleanFlags: string[] = [],\n): ParsedArgs {\n\tconst positional: string[] = [];\n\tconst options: Record<string, boolean | string> = {};\n\n\tfor (let i = 0; i < args.length; i++) {\n\t\tconst arg = args[i];\n\t\tif (!arg) continue;\n\n\t\tif (arg.startsWith(\"--\")) {\n\t\t\tconst longArg = arg.slice(2);\n\n\t\t\tif (longArg.includes(\"=\")) {\n\t\t\t\tconst [key, ...valueParts] = longArg.split(\"=\");\n\t\t\t\tif (key) {\n\t\t\t\t\toptions[key] = valueParts.join(\"=\");\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tconst key = longArg;\n\t\t\tconst nextArg = args[i + 1];\n\n\t\t\tif (booleanFlags.includes(key)) {\n\t\t\t\toptions[key] = true;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tif (nextArg && !nextArg.startsWith(\"--\")) {\n\t\t\t\toptions[key] = nextArg;\n\t\t\t\ti++;\n\t\t\t} else {\n\t\t\t\toptions[key] = true;\n\t\t\t}\n\t\t} else {\n\t\t\tpositional.push(arg);\n\t\t}\n\t}\n\n\treturn { options, positional };\n}\n\nexport const SEPARATOR = \"=\".repeat(80);\n\nexport function displayHeader(\n\ttitle: string,\n\tdetails: Record<string, string>,\n): void {\n\tconsole.log();\n\tconsole.log(SEPARATOR);\n\tconsole.log(`  🚀 ${title}`);\n\tconsole.log(SEPARATOR);\n\tfor (const [key, value] of Object.entries(details)) {\n\t\tconsole.log(`  • ${key}: ${value}`);\n\t}\n\tconsole.log(SEPARATOR);\n\tconsole.log();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAoBmB,OAAO,OAAO;CAChC,SAAS,OAAO,OAAO;EACtB,KAAK,OAAO;EACZ,OAAO,OAAO,MAAM,OAAO,QAAQ,OAAO,QAAQ;EAClD,CAAC;CACF,YAAY,OAAO,MAAM,OAAO,OAAO;CACvC,CAAC;AAIF,SAAgB,UACf,MACA,eAAyB,EAAE,EACd;CACb,MAAM,aAAuB,EAAE;CAC/B,MAAM,UAA4C,EAAE;AAEpD,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACrC,MAAM,MAAM,KAAK;AACjB,MAAI,CAAC,IAAK;AAEV,MAAI,IAAI,WAAW,KAAK,EAAE;GACzB,MAAM,UAAU,IAAI,MAAM,EAAE;AAE5B,OAAI,QAAQ,SAAS,IAAI,EAAE;IAC1B,MAAM,CAAC,KAAK,GAAG,cAAc,QAAQ,MAAM,IAAI;AAC/C,QAAI,IACH,SAAQ,OAAO,WAAW,KAAK,IAAI;AAEpC;;GAGD,MAAM,MAAM;GACZ,MAAM,UAAU,KAAK,IAAI;AAEzB,OAAI,aAAa,SAAS,IAAI,EAAE;AAC/B,YAAQ,OAAO;AACf;;AAGD,OAAI,WAAW,CAAC,QAAQ,WAAW,KAAK,EAAE;AACzC,YAAQ,OAAO;AACf;SAEA,SAAQ,OAAO;QAGhB,YAAW,KAAK,IAAI;;AAItB,QAAO;EAAE;EAAS;EAAY;;AAG/B,MAAa,YAAY,IAAI,OAAO,GAAG;AAEvC,SAAgB,cACf,OACA,SACO;AACP,SAAQ,KAAK;AACb,SAAQ,IAAI,UAAU;AACtB,SAAQ,IAAI,QAAQ,QAAQ;AAC5B,SAAQ,IAAI,UAAU;AACtB,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,CACjD,SAAQ,IAAI,OAAO,IAAI,IAAI,QAAQ;AAEpC,SAAQ,IAAI,UAAU;AACtB,SAAQ,KAAK"}

package/lib/utils/fetcher.d.ts

@@ -0,0 +1,44 @@
+import { Effect, Schema } from "effect";
+import { HttpClient } from "@effect/platform";
+
+//#region src/utils/fetcher.d.ts
+
+interface FetcherOptions<T = unknown> {
+  bodyType?: "json" | "text";
+  headers?: Record<string, string>;
+  onError?: (error: unknown) => void;
+  retries?: number;
+  retryDelay?: number;
+  schema?: Schema.Schema<T, any, never>;
+  signal?: AbortSignal;
+  timeout?: number;
+}
+type HttpMethod = "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+type QueryParams = Record<string, boolean | null | number | string | undefined | Array<boolean | number | string>>;
+type RequestBody = boolean | null | number | string | unknown[] | Record<string, unknown>;
+declare class ValidationError extends Error {
+  readonly url: string;
+  readonly problems: string;
+  readonly responseData: unknown;
+  readonly attempt?: number | undefined;
+  constructor(message: string, url: string, problems: string, responseData: unknown, attempt?: number | undefined);
+  toString(): string;
+  getProblemsString(): string;
+}
+declare class FetcherError extends Error {
+  readonly url: string;
+  readonly status?: number | undefined;
+  readonly responseData?: unknown | undefined;
+  readonly attempt?: number | undefined;
+  constructor(message: string, url: string, status?: number | undefined, responseData?: unknown | undefined, attempt?: number | undefined);
+  toString(): string;
+}
+declare function fetcher<T = unknown>(input: string, method?: HttpMethod, options?: FetcherOptions<T>, params?: QueryParams, body?: RequestBody): Effect.Effect<T, FetcherError | ValidationError, HttpClient.HttpClient>;
+declare function get<T = unknown>(url: string, options?: FetcherOptions<T>, params?: QueryParams): Effect.Effect<T, ValidationError | FetcherError, HttpClient.HttpClient>;
+declare function post<T = unknown>(url: string, body?: RequestBody, options?: FetcherOptions<T>, params?: QueryParams): Effect.Effect<T, ValidationError | FetcherError, HttpClient.HttpClient>;
+declare function put<T = unknown>(url: string, body?: RequestBody, options?: FetcherOptions<T>, params?: QueryParams): Effect.Effect<T, ValidationError | FetcherError, HttpClient.HttpClient>;
+declare function patch<T = unknown>(url: string, body?: RequestBody, options?: FetcherOptions<T>, params?: QueryParams): Effect.Effect<T, ValidationError | FetcherError, HttpClient.HttpClient>;
+declare function del<T = unknown>(url: string, options?: FetcherOptions<T>, params?: QueryParams): Effect.Effect<T, ValidationError | FetcherError, HttpClient.HttpClient>;
+//#endregion
+export { FetcherError, FetcherOptions, HttpMethod, QueryParams, RequestBody, ValidationError, del, fetcher, get, patch, post, put };
+//# sourceMappingURL=fetcher.d.ts.map

package/lib/utils/fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.d.ts","names":[],"sources":["../../src/utils/fetcher.ts"],"sourcesContent":[],"mappings":"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"}