@eunjae/il 1.2.0 → 1.3.0

package/dist/{scripts/il.mjs → cli/index.mjs}

@@ -1,17 +1,32 @@
 #!/usr/bin/env node
-import { access, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
+import { access, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
+import path from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import lockfile from "proper-lockfile";
 import { Octokit } from "octokit";
 import { DateTime } from "luxon";
-import lockfile from "proper-lockfile";
 import { createHash } from "node:crypto";
 import { ulid } from "ulid";
+import { fileURLToPath } from "node:url";
 
+//#region lib/constants.ts
+const APP_NAME = "il";
+const APP_DIR = `.${APP_NAME}`;
+const LOCK_DIR = ".lock";
+const LOCK_FILE = "store.lock";
+const TASKS_DIR = "tasks";
+const STATUS_ORDER = [
+	"backlog",
+	"active",
+	"paused",
+	"completed",
+	"cancelled"
+];
+
+//#endregion
 //#region lib/json.ts
 const readJsonFile = async (filePath) => {
 	const raw = await readFile(filePath, "utf8");
@@ -25,12 +40,7 @@ const writeJsonAtomic = async (filePath, data) => {
 };
 
 //#endregion
-//#region lib/aliasRepo.ts
-const emptyAliases = () => ({
-	T: {},
-	R: {}
-});
-const aliasFilePath = (workspaceRoot) => path.join(workspaceRoot, "aliases.json");
+//#region lib/config.ts
 const fileExists$2 = async (filePath) => {
 	try {
 		await access(filePath);
@@ -39,62 +49,194 @@ const fileExists$2 = async (filePath) => {
 		return false;
 	}
 };
-const readAliases = async (workspaceRoot) => {
-	const filePath = aliasFilePath(workspaceRoot);
-	if (!await fileExists$2(filePath)) return emptyAliases();
-	const data = await readJsonFile(filePath);
+const resolveGlobalConfigPath = () => {
+	const configHome = process.env.XDG_CONFIG_HOME ?? path.join(homedir(), ".config");
+	return path.join(configHome, APP_NAME, "config.json");
+};
+const readConfigFile = async (filePath) => {
+	if (!await fileExists$2(filePath)) return {};
+	return await readJsonFile(filePath) ?? {};
+};
+const resolveGithubToken = async (workspaceRoot) => {
+	if (process.env.IL_GITHUB_TOKEN) return process.env.IL_GITHUB_TOKEN;
+	const workspaceConfig = await readConfigFile(path.join(workspaceRoot, "config.json"));
+	if (workspaceConfig.github?.token) return workspaceConfig.github.token;
+	return (await readConfigFile(resolveGlobalConfigPath())).github?.token ?? null;
+};
+
+//#endregion
+//#region lib/workspace.ts
+const exists = async (filePath) => {
+	try {
+		await access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const findGitRoot = async (startDir) => {
+	let current = path.resolve(startDir);
+	while (true) {
+		if (await exists(path.join(current, ".git"))) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+};
+const resolveGlobalWorkspaceRoot = () => {
+	const dataHome = process.env.XDG_DATA_HOME ?? path.join(homedir(), ".local", "share");
+	return path.join(dataHome, APP_NAME);
+};
+const resolveWorkspace = async (options) => {
+	if (options.store) return {
+		root: path.resolve(options.store),
+		kind: "explicit"
+	};
+	const repoRoot = await findGitRoot(options.cwd ?? process.cwd());
+	if (options.repo) {
+		if (!repoRoot) throw new Error("Not inside a git repository");
+		return {
+			root: path.join(repoRoot, APP_DIR),
+			kind: "repo"
+		};
+	}
+	if (options.global) return {
+		root: resolveGlobalWorkspaceRoot(),
+		kind: "global"
+	};
+	if (repoRoot) {
+		const repoWorkspace = path.join(repoRoot, APP_DIR);
+		if (await exists(repoWorkspace)) return {
+			root: repoWorkspace,
+			kind: "repo"
+		};
+	}
 	return {
-		T: data.T ?? {},
-		R: data.R ?? {}
+		root: resolveGlobalWorkspaceRoot(),
+		kind: "global"
 	};
 };
-const writeAliases = async (workspaceRoot, aliases) => {
-	await writeJsonAtomic(aliasFilePath(workspaceRoot), aliases);
+const ensureWorkspaceLayout = async (workspaceRoot) => {
+	await mkdir(path.join(workspaceRoot, TASKS_DIR), { recursive: true });
+	await mkdir(path.join(workspaceRoot, LOCK_DIR), { recursive: true });
+	await Promise.all(STATUS_ORDER.map((status) => mkdir(path.join(workspaceRoot, TASKS_DIR, status), { recursive: true })));
 };
-const parseAlias = (alias) => {
-	const match = alias.match(/^([TR])(\d+)$/);
-	if (!match) return null;
+
+//#endregion
+//#region lib/lock.ts
+const withWorkspaceLock = async (workspaceRoot, fn) => {
+	await ensureWorkspaceLayout(workspaceRoot);
+	const lockPath = path.join(workspaceRoot, LOCK_DIR, LOCK_FILE);
+	await writeFile(lockPath, "", { flag: "a" });
+	const release = await lockfile.lock(lockPath, {
+		stale: 6e4,
+		retries: {
+			retries: 5,
+			factor: 1.5,
+			minTimeout: 50,
+			maxTimeout: 1e3
+		}
+	});
+	try {
+		return await fn();
+	} finally {
+		await release();
+	}
+};
+
+//#endregion
+//#region lib/time.ts
+const DEFAULT_ZONE = "Europe/Paris";
+const toIsoDate = (value, label) => {
+	const date = value.toISODate();
+	if (!date) throw new Error(`Failed to generate ${label} date`);
+	return date;
+};
+const buildDateRange = (start, end) => {
+	const dates = [];
+	let cursor = start.startOf("day");
+	const final = end.startOf("day");
+	while (cursor <= final) {
+		dates.push(toIsoDate(cursor, "range"));
+		cursor = cursor.plus({ days: 1 });
+	}
+	return dates;
+};
+const nowIso = () => {
+	const value = DateTime.now().setZone(DEFAULT_ZONE).toISO();
+	if (!value) throw new Error("Failed to generate timestamp");
+	return value;
+};
+const todayDate = (date) => {
+	const value = date ? DateTime.fromISO(date, { zone: DEFAULT_ZONE }).toISODate() : DateTime.now().setZone(DEFAULT_ZONE).toISODate();
+	if (!value) throw new Error("Failed to generate date");
+	return value;
+};
+const listDatesForScope = (scope) => {
+	const now = DateTime.now().setZone(DEFAULT_ZONE);
+	switch (scope) {
+		case "today": return [toIsoDate(now, "today")];
+		case "yesterday": return [toIsoDate(now.minus({ days: 1 }), "yesterday")];
+		case "this_week": return buildDateRange(now.startOf("week"), now.endOf("week"));
+		case "last_week": {
+			const lastWeek = now.minus({ weeks: 1 });
+			return buildDateRange(lastWeek.startOf("week"), lastWeek.endOf("week"));
+		}
+	}
+};
+
+//#endregion
+//#region lib/pr.ts
+const parseGitHubPrUrl = (value) => {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return null;
+	}
+	const parts = url.pathname.split("/").filter(Boolean);
+	if (parts.length < 4 || parts[2] !== "pull") return null;
+	const number = Number(parts[3]);
+	if (!Number.isInteger(number)) return null;
 	return {
-		prefix: match[1],
-		key: match[2]
+		url: value,
+		provider: "github",
+		repo: {
+			host: url.host,
+			owner: parts[0],
+			name: parts[1]
+		},
+		number
 	};
 };
-const formatAliasKey = (value) => String(value).padStart(2, "0");
-const allocateAliasInMap = (aliases, prefix, taskId) => {
-	const used = new Set(Object.keys(aliases[prefix]).map((key) => Number.parseInt(key, 10)));
-	let next = 1;
-	while (used.has(next)) next += 1;
-	const key = formatAliasKey(next);
-	aliases[prefix][key] = taskId;
+const buildPrAttachment = (parsed, fetched) => {
 	return {
-		alias: `${prefix}${key}`,
-		aliases
+		url: parsed.url,
+		provider: "github",
+		repo: parsed.repo,
+		number: parsed.number,
+		fetched
 	};
 };
-const allocateAlias = async (workspaceRoot, prefix, taskId) => {
-	return allocateAliasInMap(await readAliases(workspaceRoot), prefix, taskId);
-};
-const resolveAlias = async (workspaceRoot, alias) => {
-	const parsed = parseAlias(alias);
-	if (!parsed) return null;
-	return (await readAliases(workspaceRoot))[parsed.prefix][parsed.key] ?? null;
+const fetchGitHubPr = async (parsed, token) => {
+	if (!parsed.repo || !parsed.number) return null;
+	if (!token) return null;
+	const data = (await new Octokit({ auth: token }).rest.pulls.get({
+		owner: parsed.repo.owner,
+		repo: parsed.repo.name,
+		pull_number: parsed.number
+	})).data;
+	const state = data.merged ? "merged" : data.state === "open" ? "open" : "closed";
+	return {
+		at: nowIso(),
+		title: data.title,
+		author: { login: data.user?.login ?? "unknown" },
+		state,
+		draft: data.draft ?? false,
+		updated_at: data.updated_at
+	};
 };
 
-//#endregion
-//#region lib/constants.ts
-const APP_NAME = "il";
-const APP_DIR = `.${APP_NAME}`;
-const LOCK_DIR = ".lock";
-const LOCK_FILE = "store.lock";
-const TASKS_DIR = "tasks";
-const STATUS_ORDER = [
-	"backlog",
-	"active",
-	"paused",
-	"completed",
-	"cancelled"
-];
-
 //#endregion
 //#region lib/types.ts
 const taskStatuses = [
@@ -107,18 +249,29 @@ const taskStatuses = [
 const taskTypes = ["regular", "pr_review"];
 
 //#endregion
-//#region lib/schema.ts
-const logEntrySchema = z.object({
-	ts: z.string(),
-	msg: z.string(),
-	status: z.enum(taskStatuses).optional()
-});
+//#region lib/schemas/dayAssignment.ts
 const dayAssignmentSchema = z.object({
 	date: z.string(),
-	action: z.enum(["assign", "unassign"]),
+	action: z.enum([
+		"assign",
+		"unassign",
+		"reorder"
+	]),
 	ts: z.string(),
+	order: z.number().int().positive().optional(),
 	msg: z.string().optional()
 });
+
+//#endregion
+//#region lib/schemas/logEntry.ts
+const logEntrySchema = z.object({
+	ts: z.string(),
+	msg: z.string(),
+	status: z.enum(taskStatuses).optional()
+});
+
+//#endregion
+//#region lib/schemas/pr.ts
 const prRepoSchema = z.object({
 	host: z.string(),
 	owner: z.string(),
@@ -143,6 +296,9 @@ const prAttachmentSchema = z.object({
 	number: z.number().int().positive().optional(),
 	fetched: prFetchedSchema.optional()
 });
+
+//#endregion
+//#region lib/schemas/task.ts
 const taskMetadataSchema = z.object({
 	url: z.string().optional(),
 	pr: prAttachmentSchema.optional()
@@ -173,6 +329,107 @@ const validateTaskOrThrow = (task) => {
 	return taskSchema.parse(task);
 };
 
+//#endregion
+//#region lib/id.ts
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+const base32Encode = (input) => {
+	let bits = 0;
+	let value = 0;
+	let output = "";
+	for (const byte of input) {
+		value = value << 8 | byte;
+		bits += 8;
+		while (bits >= 5) {
+			output += BASE32_ALPHABET[value >>> bits - 5 & 31];
+			bits -= 5;
+		}
+	}
+	if (bits > 0) output += BASE32_ALPHABET[value << 5 - bits & 31];
+	return output;
+};
+const generateTaskId = (taskType) => {
+	return `${taskType === "pr_review" ? "R" : "T"}${ulid()}`;
+};
+const generateStableRef = (taskType, taskId) => {
+	return `${taskType === "pr_review" ? "R" : "T"}-${base32Encode(createHash("sha256").update(taskId).digest()).slice(0, 6)}`;
+};
+
+//#endregion
+//#region lib/taskFactory.ts
+const buildTask = (input) => {
+	const id = generateTaskId(input.type);
+	const ref = generateStableRef(input.type, id);
+	const timestamp = nowIso();
+	return {
+		id,
+		ref,
+		type: input.type,
+		title: input.title,
+		status: "backlog",
+		created_at: timestamp,
+		updated_at: timestamp,
+		metadata: input.metadata ?? {},
+		logs: [],
+		day_assignments: []
+	};
+};
+
+//#endregion
+//#region lib/aliasRepo.ts
+const emptyAliases = () => ({
+	T: {},
+	R: {}
+});
+const aliasFilePath = (workspaceRoot) => path.join(workspaceRoot, "aliases.json");
+const fileExists$1 = async (filePath) => {
+	try {
+		await access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const readAliases = async (workspaceRoot) => {
+	const filePath = aliasFilePath(workspaceRoot);
+	if (!await fileExists$1(filePath)) return emptyAliases();
+	const data = await readJsonFile(filePath);
+	return {
+		T: data.T ?? {},
+		R: data.R ?? {}
+	};
+};
+const writeAliases = async (workspaceRoot, aliases) => {
+	await writeJsonAtomic(aliasFilePath(workspaceRoot), aliases);
+};
+const parseAlias = (alias) => {
+	const match = alias.match(/^([TR])(\d+)$/);
+	if (!match) return null;
+	return {
+		prefix: match[1],
+		key: match[2]
+	};
+};
+const formatAliasKey = (value) => String(value).padStart(2, "0");
+const allocateAliasInMap = (aliases, prefix, taskId) => {
+	const used = new Set(Object.keys(aliases[prefix]).map((key) => Number.parseInt(key, 10)));
+	let next = 1;
+	while (used.has(next)) next += 1;
+	const key = formatAliasKey(next);
+	aliases[prefix][key] = taskId;
+	return {
+		alias: `${prefix}${key}`,
+		aliases
+	};
+};
+const allocateAlias = async (workspaceRoot, prefix, taskId) => {
+	return allocateAliasInMap(await readAliases(workspaceRoot), prefix, taskId);
+};
+const resolveAlias = async (workspaceRoot, alias) => {
+	const parsed = parseAlias(alias);
+	if (!parsed) return null;
+	return (await readAliases(workspaceRoot))[parsed.prefix][parsed.key] ?? null;
+};
+
 //#endregion
 //#region lib/taskRepo.ts
 const taskFileName = (taskId) => `${taskId}.json`;
@@ -180,7 +437,7 @@ const getStatusDir = (workspaceRoot, status) => path.join(workspaceRoot, TASKS_D
 const getTaskPath = (workspaceRoot, status, taskId) => {
 	return path.join(getStatusDir(workspaceRoot, status), taskFileName(taskId));
 };
-const fileExists$1 = async (filePath) => {
+const fileExists = async (filePath) => {
 	try {
 		await access(filePath);
 		return true;
@@ -191,7 +448,7 @@ const fileExists$1 = async (filePath) => {
 const findTaskPathById = async (workspaceRoot, taskId) => {
 	for (const status of STATUS_ORDER) {
 		const candidate = getTaskPath(workspaceRoot, status, taskId);
-		if (await fileExists$1(candidate)) return {
+		if (await fileExists(candidate)) return {
 			filePath: candidate,
 			status
 		};
@@ -229,6 +486,116 @@ const moveTaskFile = async (workspaceRoot, taskId, fromStatus, toStatus) => {
 	return toPath;
 };
 
+//#endregion
+//#region lib/taskStore.ts
+const createTaskInStore = async (workspaceRoot, task) => {
+	const { alias, aliases } = await allocateAlias(workspaceRoot, task.type === "pr_review" ? "R" : "T", task.id);
+	await writeAliases(workspaceRoot, aliases);
+	await saveTask(workspaceRoot, task.status, task);
+	return {
+		alias,
+		task
+	};
+};
+
+//#endregion
+//#region lib/addTask.ts
+var AddTaskError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "AddTaskError";
+	}
+};
+const addTaskInputSchema = z.object({
+	type: z.enum(taskTypes),
+	title: z.string().optional(),
+	url: z.string().optional(),
+	prUrl: z.string().optional(),
+	workspaceRoot: z.string()
+});
+const addTask = async (input) => {
+	const parsedInput = addTaskInputSchema.parse(input);
+	return withWorkspaceLock(parsedInput.workspaceRoot, async () => {
+		let prAttachment;
+		let prTitle;
+		if (parsedInput.type === "pr_review" && !parsedInput.prUrl) throw new AddTaskError("MISSING_PR_URL", "PR review tasks require PR URL");
+		if (parsedInput.prUrl) {
+			const parsed = parseGitHubPrUrl(parsedInput.prUrl);
+			if (!parsed) throw new AddTaskError("INVALID_PR_URL", "Invalid PR URL");
+			const fetched = await fetchGitHubPr(parsed, await resolveGithubToken(parsedInput.workspaceRoot));
+			prAttachment = buildPrAttachment(parsed, fetched ?? void 0);
+			prTitle = fetched?.title ?? `PR #${parsed.number} ${parsed.repo.owner}/${parsed.repo.name}`;
+		}
+		const isExplicitTitle = Boolean(parsedInput.title);
+		let finalTitle = parsedInput.title ?? prTitle;
+		if (!finalTitle) throw new AddTaskError("MISSING_TITLE", "Title is required when no PR URL is provided");
+		if (parsedInput.type === "pr_review" && !isExplicitTitle) finalTitle = `Review: ${finalTitle}`;
+		const metadata = {
+			url: parsedInput.url,
+			pr: prAttachment
+		};
+		const task = buildTask({
+			type: parsedInput.type,
+			title: finalTitle,
+			metadata
+		});
+		taskSchema.parse(task);
+		return createTaskInStore(parsedInput.workspaceRoot, task);
+	});
+};
+
+//#endregion
+//#region cli/schemas/addTask.ts
+const addTaskCliSchema = z.object({
+	title: z.string().optional(),
+	type: z.enum(taskTypes),
+	url: z.string().optional(),
+	pr: z.string().optional()
+}).superRefine((data, ctx) => {
+	if (data.type === "pr_review" && !data.pr) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "PR review tasks require --pr",
+		path: ["pr"]
+	});
+});
+
+//#endregion
+//#region cli/commands/add.ts
+const registerAddCommand = (program, helpers) => {
+	program.command("add").description("add a task").argument("[title]", "task title").option("--type <type>", "regular|pr_review", "regular").option("--url <url>", "attach URL").option("--pr <url>", "attach PR URL").action(helpers.handleAction(async (title, options, command) => {
+		const parsed = addTaskCliSchema.safeParse({
+			title,
+			type: options.type ?? "regular",
+			url: options.url,
+			pr: options.pr
+		});
+		if (!parsed.success) {
+			const message = parsed.error.errors.map((issue) => issue.message).join(", ");
+			helpers.failWithHelp(command, message);
+			return;
+		}
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		try {
+			const created = await addTask({
+				type: parsed.data.type,
+				title: parsed.data.title,
+				url: parsed.data.url,
+				prUrl: parsed.data.pr,
+				workspaceRoot
+			});
+			process.stdout.write(`Created ${created.alias} ${created.task.ref} ${created.task.title}\n`);
+		} catch (error) {
+			if (error instanceof AddTaskError) {
+				helpers.failWithHelp(command, error.message);
+				return;
+			}
+			throw error;
+		}
+	}));
+};
+
 //#endregion
 //#region lib/aliasReconcile.ts
 const reconcileAliases = async (workspaceRoot) => {
@@ -250,121 +617,15 @@ const reconcileAliases = async (workspaceRoot) => {
 };
 
 //#endregion
-//#region lib/config.ts
-const fileExists = async (filePath) => {
-	try {
-		await access(filePath);
-		return true;
-	} catch {
-		return false;
-	}
-};
-const resolveGlobalConfigPath = () => {
-	const configHome = process.env.XDG_CONFIG_HOME ?? path.join(homedir(), ".config");
-	return path.join(configHome, APP_NAME, "config.json");
-};
-const readConfigFile = async (filePath) => {
-	if (!await fileExists(filePath)) return {};
-	return await readJsonFile(filePath) ?? {};
-};
-const resolveGithubToken = async (workspaceRoot) => {
-	if (process.env.IL_GITHUB_TOKEN) return process.env.IL_GITHUB_TOKEN;
-	const workspaceConfig = await readConfigFile(path.join(workspaceRoot, "config.json"));
-	if (workspaceConfig.github?.token) return workspaceConfig.github.token;
-	return (await readConfigFile(resolveGlobalConfigPath())).github?.token ?? null;
-};
-
-//#endregion
-//#region lib/time.ts
-const DEFAULT_ZONE = "Europe/Paris";
-const toIsoDate = (value, label) => {
-	const date = value.toISODate();
-	if (!date) throw new Error(`Failed to generate ${label} date`);
-	return date;
-};
-const buildDateRange = (start, end) => {
-	const dates = [];
-	let cursor = start.startOf("day");
-	const final = end.startOf("day");
-	while (cursor <= final) {
-		dates.push(toIsoDate(cursor, "range"));
-		cursor = cursor.plus({ days: 1 });
-	}
-	return dates;
-};
-const nowIso = () => {
-	const value = DateTime.now().setZone(DEFAULT_ZONE).toISO();
-	if (!value) throw new Error("Failed to generate timestamp");
-	return value;
-};
-const todayDate = (date) => {
-	const value = date ? DateTime.fromISO(date, { zone: DEFAULT_ZONE }).toISODate() : DateTime.now().setZone(DEFAULT_ZONE).toISODate();
-	if (!value) throw new Error("Failed to generate date");
-	return value;
-};
-const listDatesForScope = (scope) => {
-	const now = DateTime.now().setZone(DEFAULT_ZONE);
-	switch (scope) {
-		case "today": return [toIsoDate(now, "today")];
-		case "yesterday": return [toIsoDate(now.minus({ days: 1 }), "yesterday")];
-		case "this_week": return buildDateRange(now.startOf("week"), now.endOf("week"));
-		case "last_week": {
-			const lastWeek = now.minus({ weeks: 1 });
-			return buildDateRange(lastWeek.startOf("week"), lastWeek.endOf("week"));
-		}
-	}
-};
-
-//#endregion
-//#region lib/pr.ts
-const parseGitHubPrUrl = (value) => {
-	let url;
-	try {
-		url = new URL(value);
-	} catch {
-		return null;
-	}
-	const parts = url.pathname.split("/").filter(Boolean);
-	if (parts.length < 4 || parts[2] !== "pull") return null;
-	const number = Number(parts[3]);
-	if (!Number.isInteger(number)) return null;
-	return {
-		url: value,
-		provider: "github",
-		repo: {
-			host: url.host,
-			owner: parts[0],
-			name: parts[1]
-		},
-		number
-	};
-};
-const buildPrAttachment = (parsed, fetched) => {
-	return {
-		url: parsed.url,
-		provider: "github",
-		repo: parsed.repo,
-		number: parsed.number,
-		fetched
-	};
-};
-const fetchGitHubPr = async (parsed, token) => {
-	if (!parsed.repo || !parsed.number) return null;
-	if (!token) return null;
-	const data = (await new Octokit({ auth: token }).rest.pulls.get({
-		owner: parsed.repo.owner,
-		repo: parsed.repo.name,
-		pull_number: parsed.number
-	})).data;
-	const state = data.merged ? "merged" : data.state === "open" ? "open" : "closed";
-	return {
-		at: nowIso(),
-		title: data.title,
-		author: { login: data.user?.login ?? "unknown" },
-		state,
-		draft: data.draft ?? false,
-		updated_at: data.updated_at
-	};
+//#region cli/commands/alias.ts
+const registerAliasCommand = (program, helpers) => {
+	program.command("alias").description("alias helpers").command("reconcile").description("reconcile alias mapping").action(helpers.handleAction(async () => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		await withWorkspaceLock(workspaceRoot, async () => {
+			await reconcileAliases(workspaceRoot);
+			process.stdout.write("Aliases reconciled.\n");
+		});
+	}));
 };
 
 //#endregion
@@ -396,10 +657,78 @@ const applyTaskEdit = (task, dottedPath, rawValue) => {
 		if (!parsed) throw new Error("Invalid PR URL");
 		updated.metadata.pr = buildPrAttachment(parsed, updated.metadata.pr?.fetched);
 	}
-	return validateTaskOrThrow({
-		...updated,
-		updated_at: nowIso()
-	});
+	return validateTaskOrThrow({
+		...updated,
+		updated_at: nowIso()
+	});
+};
+
+//#endregion
+//#region lib/taskResolver.ts
+const stableRefPattern = /^[TR]-[A-Z0-9]{6}$/;
+const resolveTaskId = async (workspaceRoot, identifier) => {
+	const aliasMatch = await resolveAlias(workspaceRoot, identifier);
+	if (aliasMatch) return aliasMatch;
+	if (stableRefPattern.test(identifier)) {
+		const match = (await listAllTasks(workspaceRoot)).find((stored) => stored.task.ref === identifier);
+		if (!match) throw new Error(`Task not found for ref: ${identifier}`);
+		return match.task.id;
+	}
+	if (!await findTaskPathById(workspaceRoot, identifier)) throw new Error(`Task not found: ${identifier}`);
+	return identifier;
+};
+const resolveTask = async (workspaceRoot, identifier) => {
+	const found = await findTaskPathById(workspaceRoot, await resolveTaskId(workspaceRoot, identifier));
+	if (!found) throw new Error(`Task not found: ${identifier}`);
+	return {
+		task: await loadTaskFromPath(found.filePath),
+		status: found.status,
+		filePath: found.filePath
+	};
+};
+
+//#endregion
+//#region cli/commands/edit.ts
+const registerEditCommand = (program, helpers) => {
+	program.command("edit").description("edit a task field").argument("<id>", "task identifier").argument("<path>", "dotted path").argument("<value>", "new value").action(helpers.handleAction(async (identifier, dottedPath, value) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		await withWorkspaceLock(workspaceRoot, async () => {
+			const stored = await resolveTask(workspaceRoot, identifier);
+			const updated = applyTaskEdit(stored.task, dottedPath, value);
+			await saveTask(workspaceRoot, stored.status, updated);
+			process.stdout.write(`Updated ${updated.ref}\n`);
+		});
+	}));
+};
+
+//#endregion
+//#region lib/gitignore.ts
+const lockEntry = `${APP_DIR}/.lock/`;
+const ensureLockIgnored = async (repoRoot) => {
+	const gitignorePath = path.join(repoRoot, ".gitignore");
+	let current = "";
+	try {
+		current = await readFile(gitignorePath, "utf8");
+	} catch {
+		current = "";
+	}
+	if (current.split("\n").some((line) => line.trim() === lockEntry)) return false;
+	const separator = current.endsWith("\n") || current.length === 0 ? "" : "\n";
+	await writeFile(gitignorePath, `${current}${separator}${lockEntry}\n`, "utf8");
+	return true;
+};
+
+//#endregion
+//#region cli/commands/init.ts
+const registerInitCommand = (program, helpers) => {
+	program.command("init").description("initialize repo workspace").action(helpers.handleAction(async () => {
+		const repoRoot = await findGitRoot(process.cwd());
+		if (!repoRoot) throw new Error("Not inside a git repository");
+		const workspaceRoot = path.join(repoRoot, APP_DIR);
+		await ensureWorkspaceLayout(workspaceRoot);
+		await ensureLockIgnored(repoRoot);
+		process.stdout.write(`Initialized workspace at ${workspaceRoot}\n`);
+	}));
 };
 
 //#endregion
@@ -443,108 +772,245 @@ const formatTaskDetails = (task, alias) => {
 	if (task.day_assignments.length > 0) {
 		lines.push("day_assignments:");
 		for (const entry of task.day_assignments) {
+			const order = entry.order ? ` order:${entry.order}` : "";
 			const msg = entry.msg ? ` (${entry.msg})` : "";
-			lines.push(`- ${entry.date} ${entry.action} ${entry.ts}${msg}`);
+			lines.push(`- ${entry.date} ${entry.action}${order} ${entry.ts}${msg}`);
 		}
 	}
 	return lines.join("\n");
 };
 
 //#endregion
-//#region lib/gitignore.ts
-const lockEntry = `${APP_DIR}/.lock/`;
-const ensureLockIgnored = async (repoRoot) => {
-	const gitignorePath = path.join(repoRoot, ".gitignore");
-	let current = "";
-	try {
-		current = await readFile(gitignorePath, "utf8");
-	} catch {
-		current = "";
-	}
-	if (current.split("\n").some((line) => line.trim() === lockEntry)) return false;
-	const separator = current.endsWith("\n") || current.length === 0 ? "" : "\n";
-	await writeFile(gitignorePath, `${current}${separator}${lockEntry}\n`, "utf8");
-	return true;
+//#region lib/fsm.ts
+const transitionTable = {
+	backlog: {
+		start: "active",
+		cancel: "cancelled"
+	},
+	active: {
+		pause: "paused",
+		complete: "completed",
+		cancel: "cancelled"
+	},
+	paused: {
+		start: "active",
+		complete: "completed",
+		cancel: "cancelled"
+	},
+	completed: {},
+	cancelled: {}
+};
+const getNextStatus = (current, action) => {
+	const next = transitionTable[current][action];
+	if (!next) throw new Error(`Invalid transition: ${current} -> ${action}`);
+	return next;
 };
 
 //#endregion
-//#region lib/workspace.ts
-const exists = async (filePath) => {
-	try {
-		await access(filePath);
-		return true;
-	} catch {
-		return false;
-	}
+//#region lib/taskOperations.ts
+const defaultMessages = {
+	start: "Started task",
+	pause: "Paused task",
+	complete: "Completed task",
+	cancel: "Cancelled task"
 };
-const findGitRoot = async (startDir) => {
-	let current = path.resolve(startDir);
-	while (true) {
-		if (await exists(path.join(current, ".git"))) return current;
-		const parent = path.dirname(current);
-		if (parent === current) return null;
-		current = parent;
-	}
+const appendLog = (task, message, status) => {
+	const log = {
+		ts: nowIso(),
+		msg: message,
+		status
+	};
+	return {
+		...task,
+		logs: [...task.logs, log],
+		updated_at: nowIso()
+	};
 };
-const resolveGlobalWorkspaceRoot = () => {
-	const dataHome = process.env.XDG_DATA_HOME ?? path.join(homedir(), ".local", "share");
-	return path.join(dataHome, APP_NAME);
+const applyTransition = (task, action, message) => {
+	const nextStatus = getNextStatus(task.status, action);
+	const logMessage = message ?? defaultMessages[action];
+	const log = {
+		ts: nowIso(),
+		msg: logMessage,
+		status: nextStatus
+	};
+	return {
+		task: {
+			...task,
+			status: nextStatus,
+			updated_at: nowIso(),
+			logs: [...task.logs, log]
+		},
+		nextStatus
+	};
 };
-const resolveWorkspace = async (options) => {
-	if (options.store) return {
-		root: path.resolve(options.store),
-		kind: "explicit"
+const isAssignedOnDate = (task, date) => {
+	const latest = getLatestDayAssignment(task, date);
+	if (!latest) return false;
+	return latest.event.action === "assign" || latest.event.action === "reorder";
+};
+const getLatestDayAssignment = (task, date) => {
+	let latestIndex = -1;
+	for (let i = 0; i < task.day_assignments.length; i += 1) if (task.day_assignments[i]?.date === date) latestIndex = i;
+	if (latestIndex === -1) return null;
+	const event = task.day_assignments[latestIndex];
+	if (!event) return null;
+	return {
+		event,
+		index: latestIndex
 	};
-	const repoRoot = await findGitRoot(options.cwd ?? process.cwd());
-	if (options.repo) {
-		if (!repoRoot) throw new Error("Not inside a git repository");
-		return {
-			root: path.join(repoRoot, APP_DIR),
-			kind: "repo"
-		};
-	}
-	if (options.global) return {
-		root: resolveGlobalWorkspaceRoot(),
-		kind: "global"
+};
+const appendDayAssignment = (task, date, action, msg, order) => {
+	const event = {
+		date,
+		action,
+		ts: nowIso(),
+		order,
+		msg
 	};
-	if (repoRoot) {
-		const repoWorkspace = path.join(repoRoot, APP_DIR);
-		if (await exists(repoWorkspace)) return {
-			root: repoWorkspace,
-			kind: "repo"
-		};
-	}
 	return {
-		root: resolveGlobalWorkspaceRoot(),
-		kind: "global"
+		...task,
+		day_assignments: [...task.day_assignments, event],
+		updated_at: nowIso()
 	};
 };
-const ensureWorkspaceLayout = async (workspaceRoot) => {
-	await mkdir(path.join(workspaceRoot, TASKS_DIR), { recursive: true });
-	await mkdir(path.join(workspaceRoot, LOCK_DIR), { recursive: true });
-	await Promise.all(STATUS_ORDER.map((status) => mkdir(path.join(workspaceRoot, TASKS_DIR, status), { recursive: true })));
+
+//#endregion
+//#region cli/commands/list.ts
+const listScopes = [
+	"today",
+	"yesterday",
+	"this_week",
+	"last_week"
+];
+const isTaskStatus = (value) => {
+	return taskStatuses.includes(value);
+};
+const isListScope = (value) => {
+	return listScopes.includes(value);
+};
+const registerListCommand = (program, helpers) => {
+	program.command("list").description("list tasks").argument("[status]", "task status or date scope").action(helpers.handleAction(async (status, command) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		const aliasLookup = buildAliasLookup(await readAliases(workspaceRoot));
+		const lines = [];
+		if (status && !isTaskStatus(status) && !isListScope(status)) {
+			helpers.failWithHelp(command, `Invalid status or scope: ${status}`);
+			return;
+		}
+		if (status && isListScope(status)) {
+			const dates = listDatesForScope(status);
+			const tasks = await listAllTasks(workspaceRoot);
+			for (const entry of tasks) {
+				if (!dates.some((date) => isAssignedOnDate(entry.task, date))) continue;
+				const alias = aliasLookup.get(entry.task.id);
+				let line = formatTaskListLine(entry.task, alias);
+				if (entry.task.metadata.pr?.fetched?.state) line += ` PR:${entry.task.metadata.pr.fetched.state}`;
+				lines.push(line);
+			}
+			helpers.printLines(lines);
+			return;
+		}
+		const statuses = status ? [status] : [...taskStatuses];
+		for (const currentStatus of statuses) {
+			const stored = await listTasksByStatus(workspaceRoot, currentStatus);
+			for (const entry of stored) {
+				const alias = aliasLookup.get(entry.task.id);
+				let line = formatTaskListLine(entry.task, alias);
+				if (entry.task.metadata.pr?.fetched?.state) line += ` PR:${entry.task.metadata.pr.fetched.state}`;
+				lines.push(line);
+			}
+		}
+		helpers.printLines(lines);
+	}));
 };
 
 //#endregion
-//#region lib/lock.ts
-const withWorkspaceLock = async (workspaceRoot, fn) => {
-	await ensureWorkspaceLayout(workspaceRoot);
-	const lockPath = path.join(workspaceRoot, LOCK_DIR, LOCK_FILE);
-	await writeFile(lockPath, "", { flag: "a" });
-	const release = await lockfile.lock(lockPath, {
-		stale: 6e4,
-		retries: {
-			retries: 5,
-			factor: 1.5,
-			minTimeout: 50,
-			maxTimeout: 1e3
+//#region cli/commands/log.ts
+const registerLogCommand = (program, helpers) => {
+	program.command("log").description("append a log entry").argument("<id>", "task identifier").argument("<message>", "log message").option("--status <status>", "include status in log entry").action(helpers.handleAction(async (identifier, message, options, command) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		const status = options.status;
+		if (status && !taskStatuses.includes(status)) {
+			helpers.failWithHelp(command, `Invalid status: ${status}`);
+			return;
 		}
-	});
-	try {
-		return await fn();
-	} finally {
-		await release();
-	}
+		await withWorkspaceLock(workspaceRoot, async () => {
+			const stored = await resolveTask(workspaceRoot, identifier);
+			const updated = appendLog(stored.task, message, status);
+			await saveTask(workspaceRoot, stored.status, updated);
+			process.stdout.write(`Logged on ${updated.ref}\n`);
+		});
+	}));
+};
+
+//#endregion
+//#region cli/commands/pr.ts
+const registerPrCommands = (program, helpers) => {
+	program.command("attach-pr").description("attach PR metadata to a task").argument("<id>", "task identifier").argument("<url>", "PR URL").option("-m, --message <message>", "log message").action(helpers.handleAction(async (identifier, url, options, command) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		await withWorkspaceLock(workspaceRoot, async () => {
+			const parsed = parseGitHubPrUrl(url);
+			if (!parsed) {
+				helpers.failWithHelp(command, "Invalid PR URL");
+				return;
+			}
+			const fetched = await fetchGitHubPr(parsed, await resolveGithubToken(workspaceRoot));
+			const stored = await resolveTask(workspaceRoot, identifier);
+			const next = appendLog({
+				...stored.task,
+				metadata: {
+					...stored.task.metadata,
+					pr: buildPrAttachment(parsed, fetched ?? stored.task.metadata.pr?.fetched)
+				},
+				updated_at: nowIso()
+			}, options.message ?? `Attached PR ${url}`);
+			await saveTask(workspaceRoot, stored.status, next);
+			process.stdout.write(`Attached PR to ${next.ref}\n`);
+		});
+	}));
+	program.command("refresh").description("refresh PR metadata").argument("<id>", "task identifier").option("-m, --message <message>", "log message").action(helpers.handleAction(async (identifier, options) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		await withWorkspaceLock(workspaceRoot, async () => {
+			const stored = await resolveTask(workspaceRoot, identifier);
+			const prUrl = stored.task.metadata.pr?.url;
+			if (!prUrl) {
+				process.stdout.write("No PR attached.\n");
+				return;
+			}
+			const parsed = parseGitHubPrUrl(prUrl);
+			if (!parsed) throw new Error("Invalid PR URL");
+			const fetched = await fetchGitHubPr(parsed, await resolveGithubToken(workspaceRoot));
+			if (!fetched) throw new Error("No GitHub token configured");
+			const baseUpdated = {
+				...stored.task,
+				metadata: {
+					...stored.task.metadata,
+					pr: buildPrAttachment(parsed, fetched)
+				},
+				updated_at: nowIso()
+			};
+			const previousState = stored.task.metadata.pr?.fetched?.state;
+			const nextState = fetched.state;
+			const isTerminal = stored.task.status === "completed" || stored.task.status === "cancelled";
+			let finalTask = baseUpdated;
+			let nextStatus = stored.status;
+			if (!isTerminal && previousState !== nextState) {
+				if (nextState === "merged") {
+					const result = applyTransition(baseUpdated, "complete", options.message ?? "PR merged");
+					finalTask = result.task;
+					nextStatus = result.nextStatus;
+				} else if (nextState === "closed") {
+					const result = applyTransition(baseUpdated, "cancel", options.message ?? "PR closed without merge");
+					finalTask = result.task;
+					nextStatus = result.nextStatus;
+				}
+			}
+			await saveTask(workspaceRoot, stored.status, finalTask);
+			if (nextStatus !== stored.status) await moveTaskFile(workspaceRoot, finalTask.id, stored.status, nextStatus);
+			process.stdout.write(`Refreshed ${finalTask.ref}\n`);
+		});
+	}));
 };
 
 //#endregion
@@ -560,172 +1026,196 @@ const taskMatchesQuery = (task, query) => {
 };
 
 //#endregion
-//#region lib/id.ts
-const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
-const base32Encode = (input) => {
-	let bits = 0;
-	let value = 0;
-	let output = "";
-	for (const byte of input) {
-		value = value << 8 | byte;
-		bits += 8;
-		while (bits >= 5) {
-			output += BASE32_ALPHABET[value >>> bits - 5 & 31];
-			bits -= 5;
-		}
-	}
-	if (bits > 0) output += BASE32_ALPHABET[value << 5 - bits & 31];
-	return output;
-};
-const generateTaskId = (taskType) => {
-	return `${taskType === "pr_review" ? "R" : "T"}${ulid()}`;
-};
-const generateStableRef = (taskType, taskId) => {
-	return `${taskType === "pr_review" ? "R" : "T"}-${base32Encode(createHash("sha256").update(taskId).digest()).slice(0, 6)}`;
-};
-
-//#endregion
-//#region lib/taskFactory.ts
-const buildTask = (input) => {
-	const id = generateTaskId(input.type);
-	const ref = generateStableRef(input.type, id);
-	const timestamp = nowIso();
-	return {
-		id,
-		ref,
-		type: input.type,
-		title: input.title,
-		status: "backlog",
-		created_at: timestamp,
-		updated_at: timestamp,
-		metadata: input.metadata ?? {},
-		logs: [],
-		day_assignments: []
-	};
+//#region cli/commands/search.ts
+const registerSearchCommand = (program, helpers) => {
+	program.command("search").description("search tasks").argument("<query>", "search query").action(helpers.handleAction(async (query) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		const aliasLookup = buildAliasLookup(await readAliases(workspaceRoot));
+		const lines = (await listAllTasks(workspaceRoot)).filter((stored) => taskMatchesQuery(stored.task, query)).map((stored) => {
+			const alias = aliasLookup.get(stored.task.id);
+			let line = formatTaskListLine(stored.task, alias);
+			if (stored.task.metadata.pr?.fetched?.state) line += ` PR:${stored.task.metadata.pr.fetched.state}`;
+			return line;
+		});
+		helpers.printLines(lines);
+	}));
 };
 
 //#endregion
-//#region lib/fsm.ts
-const transitionTable = {
-	backlog: {
-		start: "active",
-		cancel: "cancelled"
-	},
-	active: {
-		pause: "paused",
-		complete: "completed",
-		cancel: "cancelled"
-	},
-	paused: {
-		start: "active",
-		complete: "completed",
-		cancel: "cancelled"
-	},
-	completed: {},
-	cancelled: {}
-};
-const getNextStatus = (current, action) => {
-	const next = transitionTable[current][action];
-	if (!next) throw new Error(`Invalid transition: ${current} -> ${action}`);
-	return next;
+//#region cli/commands/show.ts
+const registerShowCommand = (program, helpers) => {
+	program.command("show").description("show a task").argument("<id>", "task identifier").action(helpers.handleAction(async (identifier) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		const stored = await resolveTask(workspaceRoot, identifier);
+		const alias = buildAliasLookup(await readAliases(workspaceRoot)).get(stored.task.id);
+		process.stdout.write(`${formatTaskDetails(stored.task, alias)}\n`);
+	}));
 };
 
 //#endregion
-//#region lib/taskOperations.ts
-const defaultMessages = {
-	start: "Started task",
-	pause: "Paused task",
-	complete: "Completed task",
-	cancel: "Cancelled task"
-};
-const appendLog = (task, message, status) => {
-	const log = {
-		ts: nowIso(),
-		msg: message,
-		status
-	};
-	return {
-		...task,
-		logs: [...task.logs, log],
-		updated_at: nowIso()
-	};
+//#region cli/commands/today.ts
+const resolveDate = (helpers, command, dateInput) => {
+	try {
+		return todayDate(dateInput);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		helpers.failWithHelp(command, message);
+		return;
+	}
 };
-const applyTransition = (task, action, message) => {
-	const nextStatus = getNextStatus(task.status, action);
-	const logMessage = message ?? defaultMessages[action];
-	const log = {
-		ts: nowIso(),
-		msg: logMessage,
-		status: nextStatus
-	};
-	return {
-		task: {
-			...task,
-			status: nextStatus,
-			updated_at: nowIso(),
-			logs: [...task.logs, log]
-		},
-		nextStatus
-	};
+const collectAssignments = (tasks, date) => {
+	const entries = [];
+	for (const stored of tasks) {
+		const latest = getLatestDayAssignment(stored.task, date);
+		if (!latest) continue;
+		if (latest.event.action === "assign" || latest.event.action === "reorder") entries.push({
+			stored,
+			lastEvent: latest.event,
+			lastIndex: latest.index
+		});
+	}
+	return entries;
+};
+const sortAssignments = (entries) => {
+	return [...entries].sort((a, b) => {
+		const orderA = a.lastEvent.order;
+		const orderB = b.lastEvent.order;
+		if (orderA != null && orderB != null) return orderA - orderB;
+		if (orderA != null) return -1;
+		if (orderB != null) return 1;
+		return a.lastIndex - b.lastIndex;
+	});
 };
-const isAssignedOnDate = (task, date) => {
-	const events = task.day_assignments.filter((entry) => entry.date === date);
-	if (events.length === 0) return false;
-	return events[events.length - 1].action === "assign";
+const buildOrderedAssignments = (tasks, date) => {
+	return sortAssignments(collectAssignments(tasks, date));
+};
+const resolveMoveTarget = (helpers, command, position, currentIndex, total) => {
+	if (position === "up") return Math.max(0, currentIndex - 1);
+	if (position === "down") return Math.min(total - 1, currentIndex + 1);
+	if (position === "top") return 0;
+	if (position === "bottom") return total - 1;
+	const parsed = Number(position);
+	if (!Number.isInteger(parsed)) {
+		helpers.failWithHelp(command, `Invalid position: ${position}`);
+		return;
+	}
+	if (parsed < 1 || parsed > total) {
+		helpers.failWithHelp(command, `Position out of range: ${position}`);
+		return;
+	}
+	return parsed - 1;
 };
-const appendDayAssignment = (task, date, action, msg) => {
-	const event = {
-		date,
-		action,
-		ts: nowIso(),
-		msg
-	};
-	return {
-		...task,
-		day_assignments: [...task.day_assignments, event],
-		updated_at: nowIso()
-	};
+const registerTodayCommands = (program, helpers) => {
+	program.command("today").description("assign a task for today").argument("<id>", "task identifier").option("--date <date>", "YYYY-MM-DD").option("-m, --message <message>", "assignment message").action(helpers.handleAction(async (identifier, options, command) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		const date = resolveDate(helpers, command, options.date);
+		if (!date) return;
+		await withWorkspaceLock(workspaceRoot, async () => {
+			const tasks = await listAllTasks(workspaceRoot);
+			const stored = await resolveTask(workspaceRoot, identifier);
+			if (isAssignedOnDate(stored.task, date)) {
+				process.stdout.write(`Already assigned ${stored.task.ref} to ${date}\n`);
+				return;
+			}
+			const order = buildOrderedAssignments(tasks, date).length + 1;
+			const updated = appendDayAssignment(stored.task, date, "assign", options.message, order);
+			await saveTask(workspaceRoot, stored.status, updated);
+			process.stdout.write(`Assigned ${updated.ref} to ${date}\n`);
+		});
+	})).command("move").description("reorder tasks assigned to a day").argument("<id>", "task identifier").argument("<position>", "up, down, top, bottom, or 1-based position").option("--date <date>", "YYYY-MM-DD").action(helpers.handleAction(async (identifier, position, options, command) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		const date = resolveDate(helpers, command, options.date);
+		if (!date) return;
+		await withWorkspaceLock(workspaceRoot, async () => {
+			const stored = await resolveTask(workspaceRoot, identifier);
+			const ordered = buildOrderedAssignments(await listAllTasks(workspaceRoot), date);
+			const currentIndex = ordered.findIndex((entry) => entry.stored.task.id === stored.task.id);
+			if (currentIndex === -1) {
+				process.stdout.write(`Task ${stored.task.ref} is not assigned to ${date}\n`);
+				return;
+			}
+			const targetIndex = resolveMoveTarget(helpers, command, position, currentIndex, ordered.length);
+			if (targetIndex === void 0) return;
+			if (targetIndex === currentIndex) {
+				process.stdout.write(`Task ${stored.task.ref} is already in position ${currentIndex + 1}\n`);
+				return;
+			}
+			const reordered = [...ordered];
+			const [moved] = reordered.splice(currentIndex, 1);
+			if (!moved) {
+				process.stdout.write(`Task ${stored.task.ref} is not assigned to ${date}\n`);
+				return;
+			}
+			reordered.splice(targetIndex, 0, moved);
+			for (const [index, entry] of reordered.entries()) {
+				const nextOrder = index + 1;
+				if (entry.lastEvent.order === nextOrder) continue;
+				const updated = appendDayAssignment(entry.stored.task, date, "reorder", void 0, nextOrder);
+				await saveTask(workspaceRoot, entry.stored.status, updated);
+			}
+			process.stdout.write(`Moved ${stored.task.ref} to position ${targetIndex + 1}\n`);
+		});
+	}));
+	program.command("untoday").description("unassign a task from today").argument("<id>", "task identifier").option("--date <date>", "YYYY-MM-DD").action(helpers.handleAction(async (identifier, options, command) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		const date = resolveDate(helpers, command, options.date);
+		if (!date) return;
+		await withWorkspaceLock(workspaceRoot, async () => {
+			const stored = await resolveTask(workspaceRoot, identifier);
+			if (!isAssignedOnDate(stored.task, date)) {
+				process.stdout.write(`Already unassigned ${stored.task.ref} from ${date}\n`);
+				return;
+			}
+			const updated = appendDayAssignment(stored.task, date, "unassign");
+			await saveTask(workspaceRoot, stored.status, updated);
+			process.stdout.write(`Unassigned ${updated.ref} from ${date}\n`);
+		});
+	}));
 };
 
 //#endregion
-//#region lib/taskResolver.ts
-const stableRefPattern = /^[TR]-[A-Z0-9]{6}$/;
-const resolveTaskId = async (workspaceRoot, identifier) => {
-	const aliasMatch = await resolveAlias(workspaceRoot, identifier);
-	if (aliasMatch) return aliasMatch;
-	if (stableRefPattern.test(identifier)) {
-		const match = (await listAllTasks(workspaceRoot)).find((stored) => stored.task.ref === identifier);
-		if (!match) throw new Error(`Task not found for ref: ${identifier}`);
-		return match.task.id;
-	}
-	if (!await findTaskPathById(workspaceRoot, identifier)) throw new Error(`Task not found: ${identifier}`);
-	return identifier;
+//#region cli/commands/transitions.ts
+const transitionNames = [
+	"start",
+	"pause",
+	"complete",
+	"cancel"
+];
+const registerTransitionCommand = (program, helpers, name) => {
+	program.command(name).description(`${name} a task`).argument("<id>", "task identifier").option("-m, --message <message>", "custom log message").action(helpers.handleAction(async (identifier, options) => {
+		const workspaceRoot = await helpers.resolveWorkspaceFor(true);
+		await withWorkspaceLock(workspaceRoot, async () => {
+			const stored = await resolveTask(workspaceRoot, identifier);
+			const { task: updated, nextStatus } = applyTransition(stored.task, name, options.message);
+			await saveTask(workspaceRoot, stored.status, updated);
+			await moveTaskFile(workspaceRoot, updated.id, stored.status, nextStatus);
+			process.stdout.write(`Updated ${updated.ref} -> ${nextStatus}\n`);
+		});
+	}));
 };
-const resolveTask = async (workspaceRoot, identifier) => {
-	const found = await findTaskPathById(workspaceRoot, await resolveTaskId(workspaceRoot, identifier));
-	if (!found) throw new Error(`Task not found: ${identifier}`);
-	return {
-		task: await loadTaskFromPath(found.filePath),
-		status: found.status,
-		filePath: found.filePath
-	};
+const registerTransitionCommands = (program, helpers) => {
+	for (const name of transitionNames) registerTransitionCommand(program, helpers, name);
 };
 
 //#endregion
-//#region lib/taskStore.ts
-const createTaskInStore = async (workspaceRoot, task) => {
-	const { alias, aliases } = await allocateAlias(workspaceRoot, task.type === "pr_review" ? "R" : "T", task.id);
-	await writeAliases(workspaceRoot, aliases);
-	await saveTask(workspaceRoot, task.status, task);
-	return {
-		alias,
-		task
-	};
+//#region cli/commands/where.ts
+const registerWhereCommand = (program, helpers) => {
+	program.command("where").description("show resolved workspace").action(helpers.handleAction(async () => {
+		const opts = program.opts();
+		const workspace = await resolveWorkspace({
+			store: opts.store,
+			global: opts.global,
+			repo: opts.repo
+		});
+		process.stdout.write(`${workspace.root} (${workspace.kind})\n`);
+	}));
 };
 
 //#endregion
-//#region scripts/il.ts
-const program = new Command();
+//#region cli/helpers.ts
+const isPackageJson = (value) => {
+	return value !== null && typeof value === "object" && "version" in value;
+};
 const handleAction = (fn) => async (...args) => {
 	try {
 		await fn(...args);
@@ -735,16 +1225,6 @@ const handleAction = (fn) => async (...args) => {
 		process.exitCode = 1;
 	}
 };
-const resolveWorkspaceFor = async (ensure) => {
-	const opts = program.opts();
-	const workspace = await resolveWorkspace({
-		store: opts.store,
-		global: opts.global,
-		repo: opts.repo
-	});
-	if (ensure) await ensureWorkspaceLayout(workspace.root);
-	return workspace.root;
-};
 const printLines = (lines) => {
 	if (lines.length === 0) {
 		process.stdout.write("No tasks.\n");
@@ -757,20 +1237,23 @@ const failWithHelp = (command, message) => {
 	command.outputHelp();
 	process.exitCode = 1;
 };
-const listScopes = [
-	"today",
-	"yesterday",
-	"this_week",
-	"last_week"
-];
-const isTaskStatus = (value) => {
-	return taskStatuses.includes(value);
-};
-const isListScope = (value) => {
-	return listScopes.includes(value);
-};
-const isPackageJson = (value) => {
-	return value !== null && typeof value === "object" && "version" in value;
+const createCliHelpers = (program) => {
+	const resolveWorkspaceFor = async (ensure) => {
+		const opts = program.opts();
+		const workspace = await resolveWorkspace({
+			store: opts.store,
+			global: opts.global,
+			repo: opts.repo
+		});
+		if (ensure) await ensureWorkspaceLayout(workspace.root);
+		return workspace.root;
+	};
+	return {
+		handleAction,
+		resolveWorkspaceFor,
+		printLines,
+		failWithHelp
+	};
 };
 const resolvePackageVersion = async () => {
 	let current = path.dirname(fileURLToPath(import.meta.url));
@@ -789,271 +1272,27 @@ const resolvePackageVersion = async () => {
 		current = parent;
 	}
 };
+
+//#endregion
+//#region cli/index.ts
+const program = new Command();
+const helpers = createCliHelpers(program);
 const packageVersion = await resolvePackageVersion();
 program.name("il").description("Terminal task manager").option("--store <path>", "explicit workspace path").option("--global", "use global workspace").option("--repo", "use repo workspace");
 if (packageVersion) program.version(packageVersion);
 program.showHelpAfterError();
-program.command("init").description("initialize repo workspace").action(handleAction(async () => {
-	const repoRoot = await findGitRoot(process.cwd());
-	if (!repoRoot) throw new Error("Not inside a git repository");
-	const workspaceRoot = path.join(repoRoot, APP_DIR);
-	await ensureWorkspaceLayout(workspaceRoot);
-	await ensureLockIgnored(repoRoot);
-	process.stdout.write(`Initialized workspace at ${workspaceRoot}\n`);
-}));
-program.command("where").description("show resolved workspace").action(handleAction(async () => {
-	const opts = program.opts();
-	const workspace = await resolveWorkspace({
-		store: opts.store,
-		global: opts.global,
-		repo: opts.repo
-	});
-	process.stdout.write(`${workspace.root} (${workspace.kind})\n`);
-}));
-program.command("add").description("add a task").argument("[title]", "task title").option("--type <type>", "regular|pr_review", "regular").option("--url <url>", "attach URL").option("--pr <url>", "attach PR URL").action(handleAction(async (title, options, command) => {
-	const taskType = options.type;
-	if (!taskTypes.includes(taskType)) {
-		failWithHelp(command, `Invalid type: ${taskType}`);
-		return;
-	}
-	if (taskType === "pr_review" && !options.pr) {
-		failWithHelp(command, "PR review tasks require --pr");
-		return;
-	}
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	await withWorkspaceLock(workspaceRoot, async () => {
-		let prAttachment;
-		let prTitle;
-		if (options.pr) {
-			const parsed = parseGitHubPrUrl(options.pr);
-			if (!parsed) {
-				failWithHelp(command, "Invalid PR URL");
-				return;
-			}
-			const fetched = await fetchGitHubPr(parsed, await resolveGithubToken(workspaceRoot));
-			prAttachment = buildPrAttachment(parsed, fetched ?? void 0);
-			prTitle = fetched?.title ?? `PR #${parsed.number} ${parsed.repo.owner}/${parsed.repo.name}`;
-		}
-		const isExplicitTitle = Boolean(title);
-		let finalTitle = title ?? prTitle;
-		if (!finalTitle) {
-			failWithHelp(command, "Title is required when no PR URL is provided");
-			return;
-		}
-		if (taskType === "pr_review" && !isExplicitTitle) finalTitle = `Review: ${finalTitle}`;
-		const metadata = {
-			url: options.url,
-			pr: prAttachment
-		};
-		const task = buildTask({
-			type: taskType,
-			title: finalTitle,
-			metadata
-		});
-		taskSchema.parse(task);
-		const created = await createTaskInStore(workspaceRoot, task);
-		process.stdout.write(`Created ${created.alias} ${created.task.ref} ${created.task.title}\n`);
-	});
-}));
-program.command("list").description("list tasks").argument("[status]", "task status or date scope").action(handleAction(async (status, command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	const aliasLookup = buildAliasLookup(await readAliases(workspaceRoot));
-	const lines = [];
-	if (status && !isTaskStatus(status) && !isListScope(status)) {
-		failWithHelp(command, `Invalid status or scope: ${status}`);
-		return;
-	}
-	if (status && isListScope(status)) {
-		const dates = listDatesForScope(status);
-		const tasks = await listAllTasks(workspaceRoot);
-		for (const entry of tasks) {
-			if (!dates.some((date) => isAssignedOnDate(entry.task, date))) continue;
-			const alias = aliasLookup.get(entry.task.id);
-			let line = formatTaskListLine(entry.task, alias);
-			if (entry.task.metadata.pr?.fetched?.state) line += ` PR:${entry.task.metadata.pr.fetched.state}`;
-			lines.push(line);
-		}
-		printLines(lines);
-		return;
-	}
-	const statuses = status ? [status] : [...taskStatuses];
-	for (const currentStatus of statuses) {
-		const stored = await listTasksByStatus(workspaceRoot, currentStatus);
-		for (const entry of stored) {
-			const alias = aliasLookup.get(entry.task.id);
-			let line = formatTaskListLine(entry.task, alias);
-			if (entry.task.metadata.pr?.fetched?.state) line += ` PR:${entry.task.metadata.pr.fetched.state}`;
-			lines.push(line);
-		}
-	}
-	printLines(lines);
-}));
-program.command("show").description("show a task").argument("<id>", "task identifier").action(handleAction(async (identifier, command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	const stored = await resolveTask(workspaceRoot, identifier);
-	const alias = buildAliasLookup(await readAliases(workspaceRoot)).get(stored.task.id);
-	process.stdout.write(`${formatTaskDetails(stored.task, alias)}\n`);
-}));
-const addTransitionCommand = (name) => {
-	program.command(name).description(`${name} a task`).argument("<id>", "task identifier").option("-m, --message <message>", "custom log message").action(handleAction(async (identifier, options, command) => {
-		const workspaceRoot = await resolveWorkspaceFor(true);
-		await withWorkspaceLock(workspaceRoot, async () => {
-			const stored = await resolveTask(workspaceRoot, identifier);
-			const { task: updated, nextStatus } = applyTransition(stored.task, name, options.message);
-			await saveTask(workspaceRoot, stored.status, updated);
-			await moveTaskFile(workspaceRoot, updated.id, stored.status, nextStatus);
-			process.stdout.write(`Updated ${updated.ref} -> ${nextStatus}\n`);
-		});
-	}));
-};
-addTransitionCommand("start");
-addTransitionCommand("pause");
-addTransitionCommand("complete");
-addTransitionCommand("cancel");
-program.command("log").description("append a log entry").argument("<id>", "task identifier").argument("<message>", "log message").option("--status <status>", "include status in log entry").action(handleAction(async (identifier, message, options, command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	const status = options.status;
-	if (status && !taskStatuses.includes(status)) {
-		failWithHelp(command, `Invalid status: ${status}`);
-		return;
-	}
-	await withWorkspaceLock(workspaceRoot, async () => {
-		const stored = await resolveTask(workspaceRoot, identifier);
-		const updated = appendLog(stored.task, message, status);
-		await saveTask(workspaceRoot, stored.status, updated);
-		process.stdout.write(`Logged on ${updated.ref}\n`);
-	});
-}));
-program.command("edit").description("edit a task field").argument("<id>", "task identifier").argument("<path>", "dotted path").argument("<value>", "new value").action(handleAction(async (identifier, dottedPath, value, command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	await withWorkspaceLock(workspaceRoot, async () => {
-		const stored = await resolveTask(workspaceRoot, identifier);
-		const updated = applyTaskEdit(stored.task, dottedPath, value);
-		await saveTask(workspaceRoot, stored.status, updated);
-		process.stdout.write(`Updated ${updated.ref}\n`);
-	});
-}));
-program.command("search").description("search tasks").argument("<query>", "search query").action(handleAction(async (query, command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	const aliasLookup = buildAliasLookup(await readAliases(workspaceRoot));
-	printLines((await listAllTasks(workspaceRoot)).filter((stored) => taskMatchesQuery(stored.task, query)).map((stored) => {
-		const alias = aliasLookup.get(stored.task.id);
-		let line = formatTaskListLine(stored.task, alias);
-		if (stored.task.metadata.pr?.fetched?.state) line += ` PR:${stored.task.metadata.pr.fetched.state}`;
-		return line;
-	}));
-}));
-program.command("today").description("assign a task for today").argument("<id>", "task identifier").option("--date <date>", "YYYY-MM-DD").option("-m, --message <message>", "assignment message").action(handleAction(async (identifier, options, command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	let date;
-	try {
-		date = todayDate(options.date);
-	} catch (error) {
-		failWithHelp(command, error instanceof Error ? error.message : String(error));
-		return;
-	}
-	await withWorkspaceLock(workspaceRoot, async () => {
-		const stored = await resolveTask(workspaceRoot, identifier);
-		if (isAssignedOnDate(stored.task, date)) {
-			process.stdout.write(`Already assigned ${stored.task.ref} to ${date}\n`);
-			return;
-		}
-		const updated = appendDayAssignment(stored.task, date, "assign", options.message);
-		await saveTask(workspaceRoot, stored.status, updated);
-		process.stdout.write(`Assigned ${updated.ref} to ${date}\n`);
-	});
-}));
-program.command("untoday").description("unassign a task from today").argument("<id>", "task identifier").option("--date <date>", "YYYY-MM-DD").action(handleAction(async (identifier, options, command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	let date;
-	try {
-		date = todayDate(options.date);
-	} catch (error) {
-		failWithHelp(command, error instanceof Error ? error.message : String(error));
-		return;
-	}
-	await withWorkspaceLock(workspaceRoot, async () => {
-		const stored = await resolveTask(workspaceRoot, identifier);
-		if (!isAssignedOnDate(stored.task, date)) {
-			process.stdout.write(`Already unassigned ${stored.task.ref} from ${date}\n`);
-			return;
-		}
-		const updated = appendDayAssignment(stored.task, date, "unassign");
-		await saveTask(workspaceRoot, stored.status, updated);
-		process.stdout.write(`Unassigned ${updated.ref} from ${date}\n`);
-	});
-}));
-program.command("attach-pr").description("attach PR metadata to a task").argument("<id>", "task identifier").argument("<url>", "PR URL").option("-m, --message <message>", "log message").action(handleAction(async (identifier, url, options, command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	await withWorkspaceLock(workspaceRoot, async () => {
-		const parsed = parseGitHubPrUrl(url);
-		if (!parsed) {
-			failWithHelp(command, "Invalid PR URL");
-			return;
-		}
-		const fetched = await fetchGitHubPr(parsed, await resolveGithubToken(workspaceRoot));
-		const stored = await resolveTask(workspaceRoot, identifier);
-		const next = appendLog({
-			...stored.task,
-			metadata: {
-				...stored.task.metadata,
-				pr: buildPrAttachment(parsed, fetched ?? stored.task.metadata.pr?.fetched)
-			},
-			updated_at: nowIso()
-		}, options.message ?? `Attached PR ${url}`);
-		await saveTask(workspaceRoot, stored.status, next);
-		process.stdout.write(`Attached PR to ${next.ref}\n`);
-	});
-}));
-program.command("refresh").description("refresh PR metadata").argument("<id>", "task identifier").option("-m, --message <message>", "log message").action(handleAction(async (identifier, options, command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	await withWorkspaceLock(workspaceRoot, async () => {
-		const stored = await resolveTask(workspaceRoot, identifier);
-		const prUrl = stored.task.metadata.pr?.url;
-		if (!prUrl) {
-			process.stdout.write("No PR attached.\n");
-			return;
-		}
-		const parsed = parseGitHubPrUrl(prUrl);
-		if (!parsed) throw new Error("Invalid PR URL");
-		const fetched = await fetchGitHubPr(parsed, await resolveGithubToken(workspaceRoot));
-		if (!fetched) throw new Error("No GitHub token configured");
-		const baseUpdated = {
-			...stored.task,
-			metadata: {
-				...stored.task.metadata,
-				pr: buildPrAttachment(parsed, fetched)
-			},
-			updated_at: nowIso()
-		};
-		const previousState = stored.task.metadata.pr?.fetched?.state;
-		const nextState = fetched.state;
-		const isTerminal = stored.task.status === "completed" || stored.task.status === "cancelled";
-		let finalTask = baseUpdated;
-		let nextStatus = stored.status;
-		if (!isTerminal && previousState !== nextState) {
-			if (nextState === "merged") {
-				const result = applyTransition(baseUpdated, "complete", options.message ?? "PR merged");
-				finalTask = result.task;
-				nextStatus = result.nextStatus;
-			} else if (nextState === "closed") {
-				const result = applyTransition(baseUpdated, "cancel", options.message ?? "PR closed without merge");
-				finalTask = result.task;
-				nextStatus = result.nextStatus;
-			}
-		}
-		await saveTask(workspaceRoot, stored.status, finalTask);
-		if (nextStatus !== stored.status) await moveTaskFile(workspaceRoot, finalTask.id, stored.status, nextStatus);
-		process.stdout.write(`Refreshed ${finalTask.ref}\n`);
-	});
-}));
-program.command("alias").description("alias helpers").command("reconcile").description("reconcile alias mapping").action(handleAction(async (command) => {
-	const workspaceRoot = await resolveWorkspaceFor(true);
-	await withWorkspaceLock(workspaceRoot, async () => {
-		await reconcileAliases(workspaceRoot);
-		process.stdout.write("Aliases reconciled.\n");
-	});
-}));
+registerInitCommand(program, helpers);
+registerWhereCommand(program, helpers);
+registerAddCommand(program, helpers);
+registerListCommand(program, helpers);
+registerShowCommand(program, helpers);
+registerTransitionCommands(program, helpers);
+registerLogCommand(program, helpers);
+registerEditCommand(program, helpers);
+registerSearchCommand(program, helpers);
+registerTodayCommands(program, helpers);
+registerPrCommands(program, helpers);
+registerAliasCommand(program, helpers);
 program.parseAsync(process.argv);
 
 //#endregion