grimoire-framework 1.0.0

package/.grimoire/product/templates/task.hbs

@@ -0,0 +1,171 @@
+---
+template_id: task
+template_name: Task
+version: 1.0
+variables:
+  - name: id
+    type: string
+    required: true
+    prompt: "Task ID:"
+  - name: name
+    type: string
+    required: true
+    prompt: "Task name:"
+  - name: description
+    type: text
+    required: true
+    prompt: "Task description:"
+  - name: status
+    type: choice
+    required: true
+    choices: [Pending, In Progress, Completed, Blocked, Cancelled]
+    default: Pending
+  - name: type
+    type: choice
+    required: false
+    choices: [Development, Design, Testing, Documentation, Research, Bugfix, Refactor]
+    default: Development
+  - name: priority
+    type: choice
+    required: false
+    choices: [P0, P1, P2, P3]
+    default: P1
+---
+
+# Task: {{name}}
+
+**ID:** {{id}}
+**Status:** {{#ifEqual status "Pending"}}⏳{{/ifEqual}}{{#ifEqual status "In Progress"}}🔄{{/ifEqual}}{{#ifEqual status "Completed"}}✅{{/ifEqual}}{{#ifEqual status "Blocked"}}🚫{{/ifEqual}}{{#ifEqual status "Cancelled"}}❌{{/ifEqual}} {{status}}
+**Type:** {{default type "Development"}}
+**Priority:** {{default priority "P1"}}
+{{#if estimate}}**Estimate:** {{estimate}}{{/if}}
+{{#if assignee}}**Assignee:** {{assignee}}{{/if}}
+{{#if storyRef}}**Story:** {{storyRef}}{{/if}}
+**Created:** {{formatDate now "YYYY-MM-DD"}}
+
+---
+
+## Description
+
+{{description}}
+
+---
+
+{{#if inputs}}
+## Inputs
+
+{{#each inputs}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+---
+
+{{#if outputs}}
+## Expected Outputs
+
+{{#each outputs}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+---
+
+## Steps
+
+{{#if steps}}
+{{#each steps}}
+{{add @index 1}}. [{{#if this.completed}}x{{else}} {{/if}}] {{this.step}}
+{{#if this.notes}}   _Note: {{this.notes}}_{{/if}}
+{{/each}}
+{{else}}
+_Steps to be defined._
+{{/if}}
+
+---
+
+{{#if validation}}
+## Validation
+
+### Criteria
+{{#each validation.criteria}}
+- [ ] {{this}}
+{{/each}}
+
+{{#if validation.commands}}
+### Commands
+```bash
+{{#each validation.commands}}
+{{this}}
+{{/each}}
+```
+{{/if}}
+{{/if}}
+
+---
+
+{{#if dependencies}}
+## Dependencies
+
+{{#each dependencies}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+{{#if blockedBy}}
+## Blocked By
+
+{{blockedBy}}
+{{/if}}
+
+---
+
+{{#if files}}
+## Files Affected
+
+| Path | Action |
+|------|--------|
+{{#each files}}
+| `{{this.path}}` | {{this.action}} |
+{{/each}}
+{{/if}}
+
+---
+
+{{#if elicitation}}
+{{#if elicitation.enabled}}
+## Elicitation
+
+{{#each elicitation.questions}}
+### {{add @index 1}}. {{this.question}}
+{{#ifEqual this.type "choice"}}
+Options:
+{{#each this.options}}
+- {{this}}
+{{/each}}
+{{/ifEqual}}
+{{/each}}
+{{/if}}
+{{/if}}
+
+---
+
+{{#if notes}}
+## Notes
+
+{{notes}}
+{{/if}}
+
+---
+
+{{#if completedAt}}
+## Completion
+
+**Completed At:** {{completedAt}}
+{{/if}}
+
+---
+
+**Generated by:** grimoire Template Engine v2.0
+**Template Version:** task-1.0
+

package/.grimoire/product/templates/tmpl-comment-on-examples.sql

@@ -0,0 +1,158 @@
+-- COMMENT ON Examples Template
+-- Purpose: Document database objects inline using PostgreSQL COMMENT ON
+-- Created: :created_date
+-- Author: :author
+--
+-- IMPORTANT: Comments are metadata that help future developers understand the schema
+
+-- =============================================================================
+-- TABLE COMMENTS
+-- =============================================================================
+
+-- Basic table comment
+COMMENT ON TABLE :table_name IS 'Description of what this table stores and its purpose';
+
+-- Detailed table comment with usage notes
+COMMENT ON TABLE users IS
+'User accounts for the application.
+Primary user data is stored here, with profile details in user_profiles.
+RLS policies ensure users can only access their own data.
+Related tables: user_profiles, user_roles, user_sessions';
+
+-- =============================================================================
+-- COLUMN COMMENTS
+-- =============================================================================
+
+-- Standard audit columns
+COMMENT ON COLUMN :table_name.id IS 'Unique identifier (UUID v4)';
+COMMENT ON COLUMN :table_name.created_at IS 'Timestamp when record was created';
+COMMENT ON COLUMN :table_name.updated_at IS 'Timestamp of last modification';
+COMMENT ON COLUMN :table_name.deleted_at IS 'Soft delete timestamp (NULL if active)';
+
+-- Business columns with context
+COMMENT ON COLUMN users.email IS 'Primary email for login and notifications. Must be unique.';
+COMMENT ON COLUMN users.status IS 'Account status: active, pending, suspended, deleted';
+
+-- Columns with constraints explained
+COMMENT ON COLUMN orders.total_amount IS
+'Order total in cents (not dollars). Calculated from line items.
+Constraint: Must be >= 0';
+
+-- Foreign key columns
+COMMENT ON COLUMN orders.user_id IS
+'References users.id. Owner of this order.
+CASCADE on delete (user deletion removes orders).';
+
+-- JSONB columns with structure
+COMMENT ON COLUMN users.preferences IS
+'User preferences as JSONB. Structure:
+{
+  "theme": "dark" | "light",
+  "notifications": { "email": boolean, "push": boolean },
+  "language": "en" | "pt" | "es"
+}';
+
+-- =============================================================================
+-- INDEX COMMENTS
+-- =============================================================================
+
+COMMENT ON INDEX idx_users_email IS 'Unique index for email lookups and login';
+COMMENT ON INDEX idx_orders_user_id IS 'Foreign key index for user order queries';
+COMMENT ON INDEX idx_orders_created_at IS 'Date range queries on order creation';
+
+-- Composite index explanation
+COMMENT ON INDEX idx_orders_user_status IS
+'Composite index for filtering user orders by status.
+Covers queries: WHERE user_id = ? AND status = ?';
+
+-- =============================================================================
+-- CONSTRAINT COMMENTS
+-- =============================================================================
+
+-- Check constraints
+COMMENT ON CONSTRAINT orders_total_positive ON orders IS
+'Ensures total_amount is never negative';
+
+COMMENT ON CONSTRAINT users_email_format ON users IS
+'Validates email format using regex pattern';
+
+-- Foreign key constraints
+COMMENT ON CONSTRAINT orders_user_id_fkey ON orders IS
+'Links order to user. ON DELETE CASCADE removes orphan orders.';
+
+-- =============================================================================
+-- FUNCTION COMMENTS
+-- =============================================================================
+
+COMMENT ON FUNCTION update_updated_at_column() IS
+'Trigger function to auto-update updated_at column.
+Used by: All tables with updated_at column.
+Trigger timing: BEFORE UPDATE FOR EACH ROW';
+
+COMMENT ON FUNCTION calculate_order_total(UUID) IS
+'Calculates order total from line items.
+Parameters: order_id UUID
+Returns: NUMERIC(10,2) total in cents
+Usage: SELECT calculate_order_total(order_id) FROM orders';
+
+-- =============================================================================
+-- TRIGGER COMMENTS
+-- =============================================================================
+
+COMMENT ON TRIGGER trigger_orders_updated_at ON orders IS
+'Auto-updates updated_at on row modification';
+
+COMMENT ON TRIGGER trigger_orders_audit ON orders IS
+'Logs all changes to audit_log table';
+
+-- =============================================================================
+-- VIEW COMMENTS
+-- =============================================================================
+
+COMMENT ON VIEW user_dashboard IS
+'Aggregated user data for dashboard display.
+Includes: user info, order counts, recent activity.
+Performance: Uses materialized subqueries for counts.
+Refresh: Live data (not materialized)';
+
+-- =============================================================================
+-- TYPE COMMENTS (for custom types)
+-- =============================================================================
+
+-- COMMENT ON TYPE order_status IS
+-- 'Enum for order lifecycle: pending, processing, shipped, delivered, cancelled';
+
+-- =============================================================================
+-- SCHEMA COMMENTS
+-- =============================================================================
+
+COMMENT ON SCHEMA public IS 'Main application schema with user-facing tables';
+-- COMMENT ON SCHEMA audit IS 'Audit logging and compliance tracking';
+-- COMMENT ON SCHEMA analytics IS 'Aggregated data for reporting';
+
+-- =============================================================================
+-- VIEWING COMMENTS
+-- =============================================================================
+
+-- View table comments
+SELECT
+    t.table_name,
+    pg_catalog.obj_description(
+        (quote_ident(t.table_schema) || '.' || quote_ident(t.table_name))::regclass,
+        'pg_class'
+    ) AS comment
+FROM information_schema.tables t
+WHERE t.table_schema = 'public'
+AND t.table_type = 'BASE TABLE';
+
+-- View column comments
+SELECT
+    c.table_name,
+    c.column_name,
+    pg_catalog.col_description(
+        (quote_ident(c.table_schema) || '.' || quote_ident(c.table_name))::regclass,
+        c.ordinal_position
+    ) AS comment
+FROM information_schema.columns c
+WHERE c.table_schema = 'public'
+ORDER BY c.table_name, c.ordinal_position;

package/.grimoire/product/templates/tmpl-migration-script.sql

@@ -0,0 +1,91 @@
+-- Migration Script Template
+-- Migration: :migration_name
+-- Created: :created_date
+-- Author: :author
+-- Description: :description
+--
+-- IMPORTANT: Run in transaction, test with dry-run first
+-- ROLLBACK: See tmpl-rollback-script.sql for corresponding rollback
+
+BEGIN;
+
+-- =============================================================================
+-- PRE-MIGRATION CHECKS
+-- =============================================================================
+
+-- Verify prerequisites are met
+DO $$
+BEGIN
+    -- Add any precondition checks here
+    -- Example: ASSERT (SELECT EXISTS (SELECT 1 FROM :prerequisite_table));
+    RAISE NOTICE 'Pre-migration checks passed';
+END $$;
+
+-- =============================================================================
+-- SCHEMA CHANGES
+-- =============================================================================
+
+-- Create new table (if needed)
+CREATE TABLE IF NOT EXISTS :table_name (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    -- Add columns here
+    :column_name :column_type :constraints,
+
+    -- Standard audit columns
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Add column to existing table (if needed)
+-- ALTER TABLE :existing_table ADD COLUMN IF NOT EXISTS :new_column :column_type;
+
+-- Create index (if needed)
+-- CREATE INDEX IF NOT EXISTS idx_:table_:column ON :table_name (:column_name);
+
+-- =============================================================================
+-- DATA MIGRATION (if needed)
+-- =============================================================================
+
+-- Migrate data from old structure to new
+-- INSERT INTO :new_table (col1, col2)
+-- SELECT old_col1, old_col2 FROM :old_table;
+
+-- =============================================================================
+-- POST-MIGRATION SETUP
+-- =============================================================================
+
+-- Add updated_at trigger
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS trigger_update_:table_name_updated_at ON :table_name;
+CREATE TRIGGER trigger_update_:table_name_updated_at
+    BEFORE UPDATE ON :table_name
+    FOR EACH ROW
+    EXECUTE FUNCTION update_updated_at_column();
+
+-- Add table comments
+COMMENT ON TABLE :table_name IS ':table_description';
+COMMENT ON COLUMN :table_name.:column_name IS ':column_description';
+
+-- =============================================================================
+-- VERIFICATION
+-- =============================================================================
+
+DO $$
+BEGIN
+    -- Verify migration was successful
+    ASSERT (SELECT EXISTS (
+        SELECT 1 FROM information_schema.tables
+        WHERE table_name = ':table_name'
+    )), 'Table :table_name was not created';
+
+    RAISE NOTICE 'Migration completed successfully';
+END $$;
+
+COMMIT;

package/.grimoire/product/templates/tmpl-rls-granular-policies.sql

@@ -0,0 +1,104 @@
+-- Granular RLS Policies Template
+-- Table: :table_name
+-- Security Model: Granular (separate policies per operation)
+-- Created: :created_date
+--
+-- This template creates separate policies for SELECT, INSERT, UPDATE, DELETE
+-- Useful when different users have different permissions per operation
+
+-- Enable RLS on table
+ALTER TABLE :table_name ENABLE ROW LEVEL SECURITY;
+
+-- Force RLS for table owner too (recommended for security)
+ALTER TABLE :table_name FORCE ROW LEVEL SECURITY;
+
+-- =============================================================================
+-- SELECT POLICY - Who can read rows
+-- =============================================================================
+DROP POLICY IF EXISTS ":table_name_select" ON :table_name;
+CREATE POLICY ":table_name_select"
+ON :table_name
+FOR SELECT
+TO authenticated
+USING (
+    -- Owner can read their own rows
+    auth.uid() = user_id
+    -- OR user has read permission via role
+    OR EXISTS (
+        SELECT 1 FROM user_roles
+        WHERE user_id = auth.uid()
+        AND role IN ('admin', 'reader')
+    )
+);
+
+-- =============================================================================
+-- INSERT POLICY - Who can create rows
+-- =============================================================================
+DROP POLICY IF EXISTS ":table_name_insert" ON :table_name;
+CREATE POLICY ":table_name_insert"
+ON :table_name
+FOR INSERT
+TO authenticated
+WITH CHECK (
+    -- User can only insert rows they will own
+    auth.uid() = user_id
+    -- OR user has creator permission
+    OR EXISTS (
+        SELECT 1 FROM user_roles
+        WHERE user_id = auth.uid()
+        AND role IN ('admin', 'creator')
+    )
+);
+
+-- =============================================================================
+-- UPDATE POLICY - Who can modify rows
+-- =============================================================================
+DROP POLICY IF EXISTS ":table_name_update" ON :table_name;
+CREATE POLICY ":table_name_update"
+ON :table_name
+FOR UPDATE
+TO authenticated
+USING (
+    -- Can only see rows to update if owner
+    auth.uid() = user_id
+    OR EXISTS (
+        SELECT 1 FROM user_roles
+        WHERE user_id = auth.uid()
+        AND role IN ('admin', 'editor')
+    )
+)
+WITH CHECK (
+    -- Can only update to valid state
+    auth.uid() = user_id
+    OR EXISTS (
+        SELECT 1 FROM user_roles
+        WHERE user_id = auth.uid()
+        AND role IN ('admin', 'editor')
+    )
+);
+
+-- =============================================================================
+-- DELETE POLICY - Who can delete rows
+-- =============================================================================
+DROP POLICY IF EXISTS ":table_name_delete" ON :table_name;
+CREATE POLICY ":table_name_delete"
+ON :table_name
+FOR DELETE
+TO authenticated
+USING (
+    -- Only owner or admin can delete
+    auth.uid() = user_id
+    OR EXISTS (
+        SELECT 1 FROM user_roles
+        WHERE user_id = auth.uid()
+        AND role = 'admin'
+    )
+);
+
+-- =============================================================================
+-- VERIFICATION
+-- =============================================================================
+-- Test these policies with:
+-- SET LOCAL ROLE authenticated;
+-- SET LOCAL request.jwt.claims = '{"sub": "user-uuid-here"}';
+-- SELECT * FROM :table_name; -- Should only return authorized rows

package/.grimoire/product/templates/tmpl-rls-kiss-policy.sql

@@ -0,0 +1,10 @@
+-- KISS single FOR ALL policy template (owner-only by column user_id)
+ALTER TABLE :table ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS ":table_kiss_all" ON :table;
+CREATE POLICY ":table_kiss_all"
+ON :table
+FOR ALL
+TO authenticated
+USING (auth.uid() = user_id)
+WITH CHECK (auth.uid() = user_id);

package/.grimoire/product/templates/tmpl-rls-roles.sql

@@ -0,0 +1,135 @@
+-- RLS Roles Template
+-- Role-Based Access Control (RBAC) foundation for RLS policies
+-- Created: :created_date
+--
+-- This template sets up the foundation for role-based RLS policies
+
+-- =============================================================================
+-- ROLES TABLE
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS roles (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name TEXT NOT NULL UNIQUE,
+    description TEXT,
+    permissions JSONB DEFAULT '[]'::JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Insert default roles
+INSERT INTO roles (name, description, permissions) VALUES
+    ('admin', 'Full system access', '["*"]'::JSONB),
+    ('editor', 'Can read and modify content', '["read", "write", "update"]'::JSONB),
+    ('viewer', 'Read-only access', '["read"]'::JSONB),
+    ('creator', 'Can create new content', '["read", "write"]'::JSONB)
+ON CONFLICT (name) DO NOTHING;
+
+-- =============================================================================
+-- USER ROLES TABLE (Many-to-Many)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS user_roles (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+    role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
+    granted_by UUID REFERENCES auth.users(id),
+    granted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    expires_at TIMESTAMPTZ, -- NULL means never expires
+
+    UNIQUE(user_id, role_id)
+);
+
+-- Index for fast role lookups
+CREATE INDEX IF NOT EXISTS idx_user_roles_user_id ON user_roles(user_id);
+CREATE INDEX IF NOT EXISTS idx_user_roles_role_id ON user_roles(role_id);
+
+-- =============================================================================
+-- HELPER FUNCTIONS FOR RLS
+-- =============================================================================
+
+-- Check if user has a specific role
+CREATE OR REPLACE FUNCTION has_role(role_name TEXT)
+RETURNS BOOLEAN AS $$
+BEGIN
+    RETURN EXISTS (
+        SELECT 1
+        FROM user_roles ur
+        JOIN roles r ON ur.role_id = r.id
+        WHERE ur.user_id = auth.uid()
+        AND r.name = role_name
+        AND (ur.expires_at IS NULL OR ur.expires_at > NOW())
+    );
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER STABLE;
+
+-- Check if user has any of the specified roles
+CREATE OR REPLACE FUNCTION has_any_role(role_names TEXT[])
+RETURNS BOOLEAN AS $$
+BEGIN
+    RETURN EXISTS (
+        SELECT 1
+        FROM user_roles ur
+        JOIN roles r ON ur.role_id = r.id
+        WHERE ur.user_id = auth.uid()
+        AND r.name = ANY(role_names)
+        AND (ur.expires_at IS NULL OR ur.expires_at > NOW())
+    );
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER STABLE;
+
+-- Check if user has a specific permission
+CREATE OR REPLACE FUNCTION has_permission(permission TEXT)
+RETURNS BOOLEAN AS $$
+BEGIN
+    RETURN EXISTS (
+        SELECT 1
+        FROM user_roles ur
+        JOIN roles r ON ur.role_id = r.id
+        WHERE ur.user_id = auth.uid()
+        AND (
+            r.permissions @> '["*"]'::JSONB
+            OR r.permissions @> to_jsonb(permission)
+        )
+        AND (ur.expires_at IS NULL OR ur.expires_at > NOW())
+    );
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER STABLE;
+
+-- =============================================================================
+-- RLS ON ROLES TABLES
+-- =============================================================================
+
+-- Roles table: Admins can manage, everyone can read
+ALTER TABLE roles ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "roles_select" ON roles
+FOR SELECT TO authenticated
+USING (true);
+
+CREATE POLICY "roles_admin" ON roles
+FOR ALL TO authenticated
+USING (has_role('admin'))
+WITH CHECK (has_role('admin'));
+
+-- User roles: Users see their own, admins see all
+ALTER TABLE user_roles ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "user_roles_select" ON user_roles
+FOR SELECT TO authenticated
+USING (user_id = auth.uid() OR has_role('admin'));
+
+CREATE POLICY "user_roles_admin" ON user_roles
+FOR ALL TO authenticated
+USING (has_role('admin'))
+WITH CHECK (has_role('admin'));
+
+-- =============================================================================
+-- USAGE EXAMPLE IN OTHER POLICIES
+-- =============================================================================
+--
+-- CREATE POLICY "my_table_select" ON my_table
+-- FOR SELECT TO authenticated
+-- USING (
+--     user_id = auth.uid()
+--     OR has_any_role(ARRAY['admin', 'viewer'])
+-- );
+--