argos-harness 0.1.0

package/assets/skills/zod-4/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: zod-4
+description: Zod 4 schema validation patterns. Trigger: When using Zod for validation - breaking changes from v3.
+---
+
+## Breaking Changes from Zod 3
+
+```typescript
+// ❌ Zod 3 (OLD)
+z.string().email()
+z.string().uuid()
+z.string().url()
+z.string().nonempty()
+z.object({ name: z.string() }).required_error("Required")
+
+// ✅ Zod 4 (NEW)
+z.email()
+z.uuid()
+z.url()
+z.string().min(1)
+z.object({ name: z.string() }, { error: "Required" })
+```
+
+## Basic Schemas
+
+```typescript
+import { z } from "zod";
+
+// Primitives
+const stringSchema = z.string();
+const numberSchema = z.number();
+const booleanSchema = z.boolean();
+const dateSchema = z.date();
+
+// Top-level validators (Zod 4)
+const emailSchema = z.email();
+const uuidSchema = z.uuid();
+const urlSchema = z.url();
+
+// With constraints
+const nameSchema = z.string().min(1).max(100);
+const ageSchema = z.number().int().positive().max(150);
+const priceSchema = z.number().min(0).multipleOf(0.01);
+```
+
+## Object Schemas
+
+```typescript
+const userSchema = z.object({
+  id: z.uuid(),
+  email: z.email({ error: "Invalid email address" }),
+  name: z.string().min(1, { error: "Name is required" }),
+  age: z.number().int().positive().optional(),
+  role: z.enum(["admin", "user", "guest"]),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+type User = z.infer<typeof userSchema>;
+
+// Parsing
+const user = userSchema.parse(data);  // Throws on error
+const result = userSchema.safeParse(data);  // Returns { success, data/error }
+
+if (result.success) {
+  console.log(result.data);
+} else {
+  console.log(result.error.issues);
+}
+```
+
+## Arrays and Records
+
+```typescript
+// Arrays
+const tagsSchema = z.array(z.string()).min(1).max(10);
+const numbersSchema = z.array(z.number()).nonempty();
+
+// Records (objects with dynamic keys)
+const scoresSchema = z.record(z.string(), z.number());
+// { [key: string]: number }
+
+// Tuples
+const coordinatesSchema = z.tuple([z.number(), z.number()]);
+// [number, number]
+```
+
+## Unions and Discriminated Unions
+
+```typescript
+// Simple union
+const stringOrNumber = z.union([z.string(), z.number()]);
+
+// Discriminated union (more efficient)
+const resultSchema = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("success"), data: z.unknown() }),
+  z.object({ status: z.literal("error"), error: z.string() }),
+]);
+```
+
+## Transformations
+
+```typescript
+// Transform during parsing
+const lowercaseEmail = z.email().transform(email => email.toLowerCase());
+
+// Coercion (convert types)
+const numberFromString = z.coerce.number();  // "42" → 42
+const dateFromString = z.coerce.date();      // "2024-01-01" → Date
+
+// Preprocessing
+const trimmedString = z.preprocess(
+  val => typeof val === "string" ? val.trim() : val,
+  z.string()
+);
+```
+
+## Refinements
+
+```typescript
+const passwordSchema = z.string()
+  .min(8)
+  .refine(val => /[A-Z]/.test(val), {
+    message: "Must contain uppercase letter",
+  })
+  .refine(val => /[0-9]/.test(val), {
+    message: "Must contain number",
+  });
+
+// With superRefine for multiple errors
+const formSchema = z.object({
+  password: z.string(),
+  confirmPassword: z.string(),
+}).superRefine((data, ctx) => {
+  if (data.password !== data.confirmPassword) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Passwords don't match",
+      path: ["confirmPassword"],
+    });
+  }
+});
+```
+
+## Optional and Nullable
+
+```typescript
+// Optional (T | undefined)
+z.string().optional()
+
+// Nullable (T | null)
+z.string().nullable()
+
+// Both (T | null | undefined)
+z.string().nullish()
+
+// Default values
+z.string().default("unknown")
+z.number().default(() => Math.random())
+```
+
+## Error Handling
+
+```typescript
+// Zod 4: Use 'error' param instead of 'message'
+const schema = z.object({
+  name: z.string({ error: "Name must be a string" }),
+  email: z.email({ error: "Invalid email format" }),
+  age: z.number().min(18, { error: "Must be 18 or older" }),
+});
+
+// Custom error map
+const customSchema = z.string({
+  error: (issue) => {
+    if (issue.code === "too_small") {
+      return "String is too short";
+    }
+    return "Invalid string";
+  },
+});
+```
+
+## React Hook Form Integration
+
+```typescript
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+
+const schema = z.object({
+  email: z.email(),
+  password: z.string().min(8),
+});
+
+type FormData = z.infer<typeof schema>;
+
+function Form() {
+  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register("email")} />
+      {errors.email && <span>{errors.email.message}</span>}
+    </form>
+  );
+}
+```
+
+## Keywords
+zod, validation, schema, typescript, forms, parsing

package/assets/skills/zustand-5/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: zustand-5
+description: Zustand 5 state management patterns. Trigger: When managing React state with Zustand.
+---
+
+## Basic Store
+
+```typescript
+import { create } from "zustand";
+
+interface CounterStore {
+  count: number;
+  increment: () => void;
+  decrement: () => void;
+  reset: () => void;
+}
+
+const useCounterStore = create<CounterStore>((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+  reset: () => set({ count: 0 }),
+}));
+
+// Usage
+function Counter() {
+  const { count, increment, decrement } = useCounterStore();
+  return (
+    <div>
+      <span>{count}</span>
+      <button onClick={increment}>+</button>
+      <button onClick={decrement}>-</button>
+    </div>
+  );
+}
+```
+
+## Persist Middleware
+
+```typescript
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+interface SettingsStore {
+  theme: "light" | "dark";
+  language: string;
+  setTheme: (theme: "light" | "dark") => void;
+  setLanguage: (language: string) => void;
+}
+
+const useSettingsStore = create<SettingsStore>()(
+  persist(
+    (set) => ({
+      theme: "light",
+      language: "en",
+      setTheme: (theme) => set({ theme }),
+      setLanguage: (language) => set({ language }),
+    }),
+    {
+      name: "settings-storage",  // localStorage key
+    }
+  )
+);
+```
+
+## Selectors (Zustand 5)
+
+```typescript
+// ✅ Select specific fields to prevent unnecessary re-renders
+function UserName() {
+  const name = useUserStore((state) => state.name);
+  return <span>{name}</span>;
+}
+
+// ✅ For multiple fields, use useShallow
+import { useShallow } from "zustand/react/shallow";
+
+function UserInfo() {
+  const { name, email } = useUserStore(
+    useShallow((state) => ({ name: state.name, email: state.email }))
+  );
+  return <div>{name} - {email}</div>;
+}
+
+// ❌ AVOID: Selecting entire store (causes re-render on any change)
+const store = useUserStore();  // Re-renders on ANY state change
+```
+
+## Async Actions
+
+```typescript
+interface UserStore {
+  user: User | null;
+  loading: boolean;
+  error: string | null;
+  fetchUser: (id: string) => Promise<void>;
+}
+
+const useUserStore = create<UserStore>((set) => ({
+  user: null,
+  loading: false,
+  error: null,
+
+  fetchUser: async (id) => {
+    set({ loading: true, error: null });
+    try {
+      const response = await fetch(`/api/users/${id}`);
+      const user = await response.json();
+      set({ user, loading: false });
+    } catch (error) {
+      set({ error: "Failed to fetch user", loading: false });
+    }
+  },
+}));
+```
+
+## Slices Pattern
+
+```typescript
+// userSlice.ts
+interface UserSlice {
+  user: User | null;
+  setUser: (user: User) => void;
+  clearUser: () => void;
+}
+
+const createUserSlice = (set): UserSlice => ({
+  user: null,
+  setUser: (user) => set({ user }),
+  clearUser: () => set({ user: null }),
+});
+
+// cartSlice.ts
+interface CartSlice {
+  items: CartItem[];
+  addItem: (item: CartItem) => void;
+  removeItem: (id: string) => void;
+}
+
+const createCartSlice = (set): CartSlice => ({
+  items: [],
+  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+  removeItem: (id) => set((state) => ({
+    items: state.items.filter(i => i.id !== id)
+  })),
+});
+
+// store.ts
+type Store = UserSlice & CartSlice;
+
+const useStore = create<Store>()((...args) => ({
+  ...createUserSlice(...args),
+  ...createCartSlice(...args),
+}));
+```
+
+## Immer Middleware
+
+```typescript
+import { create } from "zustand";
+import { immer } from "zustand/middleware/immer";
+
+interface TodoStore {
+  todos: Todo[];
+  addTodo: (text: string) => void;
+  toggleTodo: (id: string) => void;
+}
+
+const useTodoStore = create<TodoStore>()(
+  immer((set) => ({
+    todos: [],
+
+    addTodo: (text) => set((state) => {
+      // Mutate directly with Immer!
+      state.todos.push({ id: crypto.randomUUID(), text, done: false });
+    }),
+
+    toggleTodo: (id) => set((state) => {
+      const todo = state.todos.find(t => t.id === id);
+      if (todo) todo.done = !todo.done;
+    }),
+  }))
+);
+```
+
+## DevTools
+
+```typescript
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+
+const useStore = create<Store>()(
+  devtools(
+    (set) => ({
+      // store definition
+    }),
+    { name: "MyStore" }  // Name in Redux DevTools
+  )
+);
+```
+
+## Outside React
+
+```typescript
+// Access store outside components
+const { count, increment } = useCounterStore.getState();
+increment();
+
+// Subscribe to changes
+const unsubscribe = useCounterStore.subscribe(
+  (state) => console.log("Count changed:", state.count)
+);
+```
+
+## Keywords
+zustand, state management, react, store, persist, middleware

package/bin/argos.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin, committed entrypoint for the `argos` binary.
+// dist/index.js is ESM and runs the CLI as a side effect of being imported
+// (it calls citty's runMain() at module-eval time), so importing it here
+// is enough to actually execute the CLI — no exported function to call.
+await import("../dist/index.js");

package/dist/commands/adopt.d.ts

@@ -0,0 +1,35 @@
+import type { FileStatus } from "../lib/managed-files.js";
+/** Written when no lint/typecheck/test script exists to build a real gate from. */
+export declare const NO_GATE_PLACEHOLDER = "echo 'argos: no lint/typecheck/test scripts detected \u2014 set qualityGate.fast manually'";
+export interface AdoptRow {
+    field: string;
+    value: string;
+    source: "imported" | "preserved" | "detected" | "default" | "info" | "warning" | "error";
+}
+export interface AdoptOptions {
+    cwd: string;
+    refresh?: boolean;
+}
+export interface AdoptReport {
+    rows: AdoptRow[];
+    configPath?: string;
+    fichaStatus?: FileStatus;
+    backupPath?: string;
+    exitCode: 0 | 1;
+    error?: string;
+}
+/**
+ * Core, testable implementation of `argos adopt [--refresh]`: writes
+ * `argos.config.json` (detecting stack/quality-gate/identity, importing
+ * `navori.config.json` when present) and injects the `ficha` managed block
+ * into `./CLAUDE.md`. Pure function of the filesystem — no process.exit.
+ */
+export declare function runAdopt(options: AdoptOptions): AdoptReport;
+export declare const adoptCommand: import("citty").CommandDef<{
+    readonly refresh: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "Regenera argos.config.json y la ficha aunque ya existan.";
+    };
+}>;
+//# sourceMappingURL=adopt.d.ts.map

package/dist/commands/adopt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.d.ts","sourceRoot":"","sources":["../../src/commands/adopt.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAK1D,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,+FACyD,CAAC;AAE1F,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;CAC1F;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CAyO3D;AAED,eAAO,MAAM,YAAY;;;;;;EAgCvB,CAAC"}