@itsflower/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 itsflower
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @itsflower/cli
+
+🌸 Scaffold structured development workflows in your project.
+
+## Usage
+
+```bash
+# With npx (Node.js)
+npx @itsflower/cli init
+
+# With bunx (Bun)
+bunx @itsflower/cli init
+```
+
+## Commands
+
+### `flower init`
+
+Initializes flower in your project by copying workflow templates to `.flower/templates/`:
+
+- `requirement.md` — Define the problem, scope, and acceptance criteria
+- `plan.md` — Break down work into ordered tasks with ACs
+- `journal.md` — Log decisions and discoveries during implementation
+- `review.md` — Post-implementation quality checklist and learnings
+
+## License
+
+MIT

package/dist/main.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+// src/main.ts
+import { defineCommand, runMain } from "citty";
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var init = defineCommand({
+  meta: {
+    name: "init",
+    description: "Initialize flower in your project"
+  },
+  run: async () => {
+    const templatesDir = resolve(__dirname, "../templates");
+    const destDir = resolve(process.cwd(), ".flower/templates");
+    await mkdir(destDir, { recursive: true });
+    const files = await readdir(templatesDir);
+    for (const file of files) {
+      const src = join(templatesDir, file);
+      const dest = join(destDir, file);
+      await writeFile(dest, await readFile(src));
+    }
+    console.log(`Copied ${files.length} templates to ${destDir}`);
+    for (const file of files) {
+      console.log(`  - ${file}`);
+    }
+    console.log("Done!");
+  }
+});
+var main = defineCommand({
+  meta: {
+    name: "flower",
+    version: "0.1.0",
+    description: "\u{1F338} flower CLI"
+  },
+  subCommands: {
+    init
+  }
+});
+runMain(main);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@itsflower/cli",
+  "version": "0.1.0",
+  "description": "🌸 flower CLI — scaffold structured development workflows",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["flower", "workflow", "cli", "templates"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/itsflower/flower"
+  },
+  "bin": {
+    "flower": "./dist/main.js"
+  },
+  "files": ["dist", "templates"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/main.ts --format esm --shims",
+    "prepack": "rm -f templates && cp -r ../../core/templates templates",
+    "postpack": "rm -rf templates && ln -s ../../core/templates templates"
+  },
+  "dependencies": {
+    "citty": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0"
+  }
+}

package/templates/journal.md

@@ -0,0 +1,46 @@
+<!-- Record knowledge and decisions during implementation. Write entries during work, not after.
+Each entry uses a structured format for future search and retrieval.
+
+Guidelines:
+- Write in plain language, not formal prose
+- Focus on WHY, not WHAT — the code shows what changed
+- Only record noteworthy events — if the plan was followed exactly, there is nothing to log
+- One entry per meaningful event — do not log routine changes
+-->
+
+## Entries
+
+<!-- Each entry must use this structured format:
+
+### [Short actionable title]
+- **tags**: [comma-separated domain keywords for search]
+- **scope**: [global | project:<name>]
+- **context**: [What was being worked on]
+- **insight**: [The decision, discovery, or deviation — focus on WHY]
+
+Example:
+
+### Switched from LIKE queries to tsvector for product search
+- **tags**: postgresql, search, performance, indexing
+- **scope**: project:catalog
+- **context**: Implementing the search endpoint (Task 2 in plan). Initial ILIKE approach showed 650ms response on 100K rows.
+- **insight**: LIKE with leading wildcard forces sequential scans. tsvector + GIN index provides O(log n) lookup, bringing response time from 650ms to 12ms. Always use tsvector for full-text search at scale.
+
+---
+
+### Input validation prevents DoS via long search queries
+- **tags**: security, validation, performance
+- **scope**: global
+- **context**: Testing edge cases on the search endpoint. 10,000-char query caused 3s parse time.
+- **insight**: Unbounded input length is both a performance risk and a DoS vector. Added 1-200 char validation returning HTTP 400. Always validate input length for text-processing endpoints.
+-->
+
+## Deviations from Plan
+
+<!-- Summarize significant differences between the plan and what was actually implemented. Fill this in at the end by pulling from entries above.
+
+Format:
+| Planned | Actual | Reason |
+| ------- | ------ | ------ |
+| [Original approach] | [What was done instead] | [Why the change] |
+-->

package/templates/plan.md

@@ -0,0 +1,93 @@
+---
+status: [in-progress | completed | rejected]
+---
+
+## 1. Overview
+
+<!-- Write 2-3 sentences stating what is being built and the general approach. Scope and direction must be clear from this section alone.
+
+Example: "Add full-text search to the product catalog API using PostgreSQL tsvector. A new search endpoint accepts keyword queries and returns products ranked by relevance. A GIN index on a generated tsvector column ensures response times stay under 200ms." -->
+
+## 2. Technical Decisions
+
+<!-- List decisions that affect multiple tasks. State WHAT was decided and WHY. Only include decisions where the choice is non-obvious or where choosing differently would significantly change the plan.
+
+Format (simple — use when the choice is clear):
+- **[Decision]**: [Rationale]
+
+Format (complex — use when alternatives were seriously considered):
+- **[Decision]**: [Rationale]
+  - Alternatives considered: [Rejected option → why rejected]
+  - Tradeoff: [What is given up]
+
+Example:
+- **PostgreSQL tsvector instead of Elasticsearch**: Avoids new infrastructure dependency; tsvector is sufficient for catalogs under 500K items and keeps the stack simple.
+  - Alternatives considered: Elasticsearch → requires new cluster, adds ops complexity not needed at current scale
+  - Tradeoff: No built-in typo tolerance or synonym expansion
+- **GIN index on a generated tsvector column**: Keeps the index in sync automatically when product data changes, no application-level trigger logic needed.
+
+Skip this section if all technical choices are obvious or only affect a single task. -->
+
+## 3. Tasks
+
+<!-- Break down the work into concrete, ordered tasks. Group related tasks under a heading when it aids readability.
+
+Each task MUST have:
+- A clear, imperative description of WHAT to do
+- **AC**: Acceptance criteria specific to this task — pass/fail verifiable
+- **Approach**: How to implement — concrete steps, files to touch, patterns to follow
+- Optionally, **Blocked by** if it depends on another task completing first
+
+Guidelines:
+- One logical change per task — if the description says "X and Y", split into two tasks
+- Order tasks by dependency — tasks that unblock others come first
+- Use precise verbs: implement, add, remove, migrate, validate — not "handle", "deal with", "look into"
+- AC must be specific enough to verify programmatically. Bad: "works correctly". Good: "GET /api/products/search?q=mouse returns HTTP 200 with matching products"
+-->
+
+### [Group Name]
+
+- [ ] **Task 1**: [Description]
+  - AC:
+    - [Concrete testable condition]
+    - [Concrete testable condition]
+  - Approach: [How to implement — concrete steps, files to touch, patterns to follow]
+
+- [ ] **Task 2**: [Description]
+  - AC:
+    - [Concrete testable condition]
+  - Approach: [How to implement]
+  - Blocked by: Task 1
+
+### [Group Name]
+
+- [ ] **Task 3**: [Description]
+  - AC:
+    - [Concrete testable condition]
+  - Approach: [How to implement]
+
+## 4. Dependencies
+
+<!-- List anything that must exist or be available BEFORE implementation can begin. Skip items already in place. Skip section entirely if no dependencies exist. -->
+
+### Internal Dependencies
+
+<!-- Code, modules, or infrastructure within the project that tasks depend on — only if NOT already listed as a task above. If it is, use "Blocked by" on the task instead. -->
+
+### External Dependencies
+
+<!-- Third-party services, APIs, packages, credentials, or infrastructure outside the project's control. Example: "PostgreSQL 15+ with full-text search support", "API gateway configured to allow the new endpoint". -->
+
+## 5. Risks & Mitigation
+
+<!-- Identify what could go wrong during implementation and how to handle it. Focus on risks that would change the plan if they materialize. Skip generic risks like "bugs might occur". Skip section entirely if no meaningful risks exist.
+
+Format:
+- **Risk**: [What could go wrong]
+  - Impact: [What happens if it does]
+  - Mitigation: [How to prevent or respond]
+-->
+
+## Rejection Reason
+
+<!-- Only fill this section if status is "rejected". Explain why the requirement is not feasible — cite specific constraints, technical limitations, or contradictions that make it unachievable. Delete this section if the plan is feasible. -->

package/templates/requirement.md

@@ -0,0 +1,45 @@
+---
+type: [feature | enhancement | bug-fix | refactor]
+size: [small | medium | large]
+---
+
+## 1. Problem
+
+<!-- Who is affected, when it occurs, what goes wrong. 2–5 bullets. No solutions. -->
+
+## 2. User Stories
+
+<!-- "As a [user], I want [action] so that [benefit]" — include key workflows and edge cases. -->
+
+## 3. Scope
+
+### Goals
+
+<!-- Verifiable outcomes — each must be yes/no checkable. -->
+
+### Non-Goals
+
+<!-- Explicitly excluded — anything someone might reasonably assume is in scope. -->
+
+## 4. Acceptance Criteria
+
+<!-- Given [context], when [action], then [result]. Each must be pass/fail testable. -->
+
+## 5. Constraints & Prerequisites
+
+### Constraints
+
+<!-- Hard limits: tech stack, performance, security, regulations, deadlines. -->
+
+### Prerequisites
+
+<!-- Things outside this scope but required for it to work — must already exist or be completed separately. -->
+
+## 6. Glossary
+
+<!-- Domain-specific terms only. Skip section if all terms are self-explanatory. -->
+
+<!--
+| Term | Definition |
+| ---- | ---------- |
+-->

package/templates/review.md

@@ -0,0 +1,49 @@
+---
+status: [draft | completed]
+---
+
+## 1. Summary
+
+<!-- Write 2-4 sentences stating what was delivered and the overall outcome. This must be self-contained — do not assume prior context.
+
+Example: "Added full-text search to the product catalog API using PostgreSQL tsvector. Shoppers can now search products by name, description, and tags with relevance-ranked results. All acceptance criteria passed. Response time is under 150ms at p95." -->
+
+## 2. Quality Checklist
+
+<!-- Complete each item. If skipping any, note the reason.
+
+- [ ] Dead code & unused files removed
+- [ ] Project standards followed (style, structure, patterns, linting)
+- [ ] No security issues (secrets, injection, auth bypass, etc.)
+- [ ] Performance acceptable (no N+1, unnecessary re-renders, large payloads, etc.)
+- [ ] All tests pass
+- [ ] Documentation up to date (skip if no user-facing docs exist)
+-->
+
+## 3. Memories
+
+<!-- Record knowledge gained during this quest for future retrieval.
+
+Each entry:
+- **title**: Short, actionable (5-12 words)
+- **content**: Detailed explanation with context and examples
+- **tags**: Comma-separated domain keywords
+- **scope**: global | project:<name>
+
+### [Title]
+- **content**: [Detailed explanation]
+- **tags**: [e.g., search, backend, postgresql]
+- **scope**: [e.g., global, project:catalog]
+
+Example:
+
+### PostgreSQL tsvector requires GIN index for acceptable performance
+- **content**: Without a GIN index on the tsvector column, full-text search queries degrade to sequential scans. On a 100K row table, query time dropped from 800ms to 12ms after adding the index. Always create a GIN index when using tsvector.
+- **tags**: postgresql, search, performance, indexing
+- **scope**: project:catalog
+
+### Test search relevance with real-world data, not synthetic data
+- **content**: Initial tests with synthetic data all passed, but real product names with typos and abbreviations exposed ranking issues. Always use a representative sample of production data for search quality tests.
+- **tags**: testing, search, data-quality
+- **scope**: global
+-->