@knpkv/jira-clockify 1.3.0 → 1.4.0

package/dist/src/cli/watchLease.js

@@ -0,0 +1,204 @@
+/**
+ * The lease that keeps two watches from writing the same hours, and the cursor that lets one resume.
+ *
+ * **Mental model**
+ *
+ * - **One writer per machine.** `jcf watch` derives what to write by subtracting what the two sides
+ *   already hold. That makes a *later* look safe, and says nothing about a *simultaneous* one: two
+ *   processes can read the same gap before either writes, and then both write it. An accidental
+ *   second terminal is enough.
+ * - **Won by creating the file, not by reading it.** Acquisition is an exclusive create, so of two
+ *   watches starting together exactly one succeeds. A read-then-write would let both conclude the
+ *   lease was free.
+ * - **A held lease is immutable.** There is no safe read-then-overwrite takeover: two contenders can
+ *   both read the same old value and each overwrite it. A lease is removed only by its owner during
+ *   orderly shutdown. After an ungraceful process death it must be removed manually, after checking
+ *   that no watch is running. Availability loses to duplicate provider writes here.
+ * - **A failure to claim is not a claim.** An unwritable config directory means no lease exists, not
+ *   that this process holds one. It stops rather than running unprotected.
+ * - **The cursor is the earliest *unresolved* instant**, not where the holder's clock was. A watch
+ *   stopped mid-block was holding prompts that had not settled; resuming from the shutdown time
+ *   would filter exactly those out and lose the block it was trying to protect.
+ *
+ * **Gotchas**
+ *
+ * - Machine-local. Two watches on two machines against one Clockify account are not covered by this,
+ *   and cannot be without an idempotency key the remote side honours.
+ * - A resume is offered only when the previous holder stopped *recently*. A cursor left behind
+ *   yesterday describes work that has long since settled, and reaching back to it would be backfill
+ *   wearing a cursor's clothes.
+ *
+ * @module
+ */
+import * as Clock from "effect/Clock";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
+import { ConfigService } from "../services/ConfigService.js";
+const LEASE_FILE = "watch.lease";
+const CURSOR_FILE = "watch.cursor";
+/** How many of the *holder's* poll intervals of silence make a lease abandoned rather than held. */
+const STALE_INTERVALS = 3;
+const Lease = Schema.Struct({
+    /** Who wrote this. The only way a watch can tell its own lease from one that replaced it. */
+    owner: Schema.optional(Schema.String),
+    heldSinceMs: Schema.Number,
+    /** Last time the holder said it was alive. */
+    refreshedAtMs: Schema.Number,
+    /** The holder's poll interval, so staleness is judged on its terms rather than a contender's. */
+    intervalSeconds: Schema.Number,
+    /** Wall clock at the holder's last look — how long it has been down, when it is. */
+    lookedUpToMs: Schema.optional(Schema.Number),
+    /** Earliest instant the holder had not yet resolved. Where a prompt resume must begin. */
+    unresolvedFromMs: Schema.optional(Schema.Number)
+});
+const decodeLease = Schema.decodeUnknownOption(Schema.fromJsonString(Lease));
+const encode = (lease) => JSON.stringify(lease);
+/**
+ * What a previous holder leaves for the next one, if anything.
+ *
+ * Two conditions, and both matter. The holder must have stopped recently — judged on *its* interval,
+ * since that is how often it was proving liveness — because a cursor from yesterday describes work
+ * that has settled and belongs to `reconcile`. And it must have said where it had got to; a lease
+ * written by an older version has no cursor and offers no resume.
+ */
+const resumePoint = (previous, nowMs) => {
+    const downMs = nowMs - (previous.lookedUpToMs ?? previous.refreshedAtMs);
+    const graceMs = Math.max(previous.intervalSeconds, 1) * STALE_INTERVALS * 1000;
+    if (downMs > graceMs)
+        return null;
+    return previous.unresolvedFromMs ?? null;
+};
+/**
+ * Whether a failed exclusive create means "someone got there first" or "this cannot be written".
+ *
+ * The distinction is the difference between standing down and running unprotected. A read-only or
+ * full config directory used to look exactly like a lease already existing, and the fallback writes
+ * that followed were swallowed too — so the watch went on to write hours with no lease on disk at
+ * all, which is precisely the situation this file exists to prevent.
+ */
+const isAlreadyExists = (error) => (error.message ?? "").includes("EEXIST") || (error.message ?? "").includes("AlreadyExists");
+/**
+ * Take the lease, unless another watch holds it.
+ *
+ * The happy path is a single exclusive create: two watches starting together cannot both win it.
+ * An existing file is never overwritten. A stale-looking timestamp cannot make a read-then-write
+ * takeover atomic, so an ungraceful crash requires explicit human cleanup.
+ */
+export const acquire = (options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const config = yield* ConfigService;
+    const dir = yield* config.configDir;
+    const file = path.join(dir, LEASE_FILE);
+    const cursorFile = path.join(dir, CURSOR_FILE);
+    const now = yield* Clock.currentTimeMillis;
+    // Two watches can start in the same millisecond, so the clock alone does not identify a holder.
+    const token = yield* Random.nextInt;
+    const owner = `${now.toString(36)}-${Math.abs(token).toString(36)}`;
+    yield* fs.makeDirectory(dir, { recursive: true }).pipe(Effect.catch(() => Effect.void));
+    const mine = {
+        owner,
+        heldSinceMs: now,
+        refreshedAtMs: now,
+        intervalSeconds: options.intervalSeconds,
+        lookedUpToMs: now,
+        unresolvedFromMs: now
+    };
+    // Read recovery state before taking ownership. Once exclusive creation succeeds there must be
+    // no interruptible work before returning the lease to the caller that installs its finalizer.
+    const previous = yield* fs.readFileString(cursorFile).pipe(Effect.map(decodeLease), Effect.catch(() => Effect.succeed(Option.none())));
+    const resumeFromMs = Option.match(previous, {
+        onNone: () => null,
+        onSome: (cursor) => resumePoint(cursor, now)
+    });
+    const created = yield* fs.writeFileString(file, encode(mine), { flag: "wx" }).pipe(Effect.as({ _tag: "Won" }), Effect.catch((error) => Effect.succeed(isAlreadyExists(error) ? { _tag: "Exists" } : { _tag: "Failed" }).pipe(Effect.tap(() => isAlreadyExists(error)
+        ? Effect.void
+        : Effect.logDebug(`Could not create ${file}: ${error.message}`)))));
+    if (created._tag === "Won") {
+        return { _tag: "Held", path: file, owner, resumeFromMs };
+    }
+    if (created._tag === "Failed") {
+        return {
+            _tag: "Unavailable",
+            reason: `could not write ${file} — nothing would stop a second watch writing the same hours`
+        };
+    }
+    const existing = yield* fs.readFileString(file).pipe(Effect.map(decodeLease), 
+    // Unreadable or malformed is not evidence that anybody holds it.
+    Effect.catch(() => Effect.succeed(Option.none())));
+    const held = Option.getOrUndefined(existing);
+    if (held === undefined || held.owner === undefined) {
+        return {
+            _tag: "Unavailable",
+            reason: `could not verify ownership of existing ${file}`
+        };
+    }
+    return { _tag: "Taken", sinceMs: held.heldSinceMs };
+});
+/** Whether the lease on disk still carries this owner's name. */
+const readStanding = (file, owner) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const current = yield* fs.readFileString(file).pipe(Effect.map((value) => ({ _tag: "Read", lease: decodeLease(value) })), Effect.catch((error) => Effect.succeed({
+        _tag: "Unavailable",
+        reason: `could not read ${file}: ${error.message}`
+    })));
+    if (current._tag === "Unavailable")
+        return current;
+    const lease = Option.getOrUndefined(current.lease);
+    if (lease === undefined || lease.owner === undefined) {
+        return {
+            _tag: "Unavailable",
+            reason: `could not verify ownership of ${file}`
+        };
+    }
+    return lease.owner === owner
+        ? { _tag: "Mine" }
+        : { _tag: "Lost", reason: "another jcf watch took over this lease" };
+});
+/**
+ * Verify that this process still owns the immutable lease.
+ *
+ * The cursor is persisted only on orderly release. Rewriting the lock while held would reintroduce
+ * a write race and buys no exclusion: ownership is the unchanged token on disk.
+ */
+export const refresh = (options) => readStanding(options.path, options.owner);
+/**
+ * Stop holding the lease, keeping the cursor in a separate file.
+ *
+ * Silent when the lease is no longer this run's. A displaced process must not remove another
+ * owner's lock or publish its cursor as the next run's resume boundary.
+ */
+export const release = (options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const standing = yield* readStanding(options.path, options.owner);
+    if (standing._tag !== "Mine")
+        return;
+    const now = yield* Clock.currentTimeMillis;
+    const cursorPath = path.join(path.dirname(options.path), CURSOR_FILE);
+    const persisted = yield* fs.writeFileString(cursorPath, encode({
+        owner: options.owner,
+        heldSinceMs: options.heldSinceMs,
+        refreshedAtMs: 0,
+        intervalSeconds: options.intervalSeconds,
+        lookedUpToMs: now,
+        unresolvedFromMs: options.unresolvedFromMs
+    })).pipe(Effect.as(true), Effect.catch((error) => Console.error(`Could not persist the watch cursor at ${cursorPath}: ${error.message}. Lease retained.`).pipe(Effect.as(false))));
+    if (!persisted)
+        return;
+    yield* fs.remove(options.path).pipe(Effect.catch(() => Effect.void));
+});
+/** Release a short-lived non-watch writer without publishing a watch resume cursor. */
+export const releaseGuard = (options) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const standing = yield* readStanding(options.path, options.owner);
+    if (standing._tag !== "Mine")
+        return;
+    yield* fs.remove(options.path).pipe(Effect.catch(() => Effect.void));
+});
+//# sourceMappingURL=watchLease.js.map

package/dist/src/cli/watchLease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchLease.js","sourceRoot":"","sources":["../../../src/cli/watchLease.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/writerGuard.d.ts

@@ -0,0 +1,37 @@
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import type * as Path from "effect/Path";
+import type { ConfigService } from "../services/ConfigService.js";
+import * as WatchLease from "./watchLease.js";
+declare const WriterGuardError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "WriterGuardError";
+} & Readonly<A>;
+/**
+ * Why a provider write could not run: `taken` means another JCF writer (usually `jcf watch`)
+ * holds the machine guard, `unavailable` that the guard could not be acquired, `lost` that the
+ * held guard stopped standing mid-operation, and `missing` that a mutation ran outside a guard.
+ */
+export declare class WriterGuardError extends WriterGuardError_base<{
+    readonly reason: "taken" | "unavailable" | "lost" | "missing";
+    readonly message: string;
+}> {
+}
+export declare const isWriterGuardError: (self: unknown) => self is {
+    _tag: "WriterGuardError";
+};
+type GuardRequirements = ConfigService | FileSystem.FileSystem | Path.Path;
+/** Provide an already-held lease to nested writer services without acquiring it again. */
+export declare const withExistingWriterGuard: <A, E, R>(lease: Extract<WatchLease.LeaseOutcome, {
+    readonly _tag: "Held";
+}>, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/** Acquire the machine guard, or reuse the live guard already enclosing this operation. */
+export declare const withWriterGuard: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | WriterGuardError, R | GuardRequirements>;
+/**
+ * Serialize one provider mutation inside the live guard.
+ *
+ * Same-fiber nesting reuses the permit. A fork gets a different fiber id and must wait for the
+ * shared semaphore; after the owning guard releases, the live-lease check fails closed.
+ */
+export declare const mutate: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | WriterGuardError, R | GuardRequirements>;
+export {};
+//# sourceMappingURL=writerGuard.d.ts.map

package/dist/src/cli/writerGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writerGuard.d.ts","sourceRoot":"","sources":["../../../src/cli/writerGuard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAEpD,OAAO,KAAK,KAAK,IAAI,MAAM,aAAa,CAAA;AAIxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;;;;AAE7C;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,sBAAqC;IACzE,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,CAAA;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAC;CAAG;AAEL,eAAO,MAAM,kBAAkB;;CAAyC,CAAA;AAqBxE,KAAK,iBAAiB,GAAG,aAAa,GAAG,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAA;AAgB1E,0FAA0F;AAC1F,eAAO,MAAM,uBAAuB,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,SACtC,OAAO,CAAC,UAAU,CAAC,YAAY,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,UAC1D,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAuBrB,CAAA;AAEH,2FAA2F;AAC3F,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC,GAAG,iBAAiB,CAwB3D,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UACpB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC,GAAG,iBAAiB,CA4B3D,CAAA"}

package/dist/src/cli/writerGuard.js

@@ -0,0 +1,92 @@
+/** One live machine writer lease shared by every provider mutation in this process. */
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as FiberSet from "effect/FiberSet";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Ref from "effect/Ref";
+import * as Semaphore from "effect/Semaphore";
+import * as WatchLease from "./watchLease.js";
+/**
+ * Why a provider write could not run: `taken` means another JCF writer (usually `jcf watch`)
+ * holds the machine guard, `unavailable` that the guard could not be acquired, `lost` that the
+ * held guard stopped standing mid-operation, and `missing` that a mutation ran outside a guard.
+ */
+export class WriterGuardError extends Data.TaggedError("WriterGuardError") {
+}
+export const isWriterGuardError = Predicate.isTagged("WriterGuardError");
+class WriterScope extends Context.Service()("jcf/WriterScope") {
+}
+class MutationScope extends Context.Service()("jcf/WriterMutationScope") {
+}
+const standingError = (reason) => new WriterGuardError({ reason: "lost", message: `Machine writer guard lost: ${reason}` });
+const verifyStanding = (scope) => Effect.gen(function* () {
+    const standing = yield* WatchLease.refresh({ path: scope.lease.path, owner: scope.lease.owner });
+    if (standing._tag !== "Mine")
+        return yield* standingError(standing.reason);
+});
+const verify = (scope) => Effect.gen(function* () {
+    if (!(yield* Ref.get(scope.active))) {
+        return yield* standingError("the owning operation already released it");
+    }
+    yield* verifyStanding(scope);
+});
+/** Provide an already-held lease to nested writer services without acquiring it again. */
+export const withExistingWriterGuard = (lease, effect) => Effect.scoped(Effect.gen(function* () {
+    const fibers = yield* FiberSet.make();
+    const cancelAndJoin = FiberSet.clear(fibers);
+    const drain = FiberSet.awaitEmpty(fibers).pipe(Effect.interruptible, Effect.onInterrupt(() => cancelAndJoin));
+    return yield* Effect.acquireUseRelease(Effect.all({ active: Ref.make(true), admission: Semaphore.make(1), mutations: Semaphore.make(1) }), ({ active, admission, mutations }) => effect.pipe(Effect.provideService(WriterScope, { active, admission, fibers, lease, mutations })), ({ active, admission }, exit) => Ref.set(active, false).pipe(
+    // Flush any admission already between the active check and FiberSet registration.
+    Effect.andThen(admission.withPermit(Effect.void)), Effect.andThen(Exit.isSuccess(exit) ? drain : cancelAndJoin)));
+}));
+/** Acquire the machine guard, or reuse the live guard already enclosing this operation. */
+export const withWriterGuard = (effect) => Effect.gen(function* () {
+    const current = yield* Effect.serviceOption(WriterScope);
+    if (Option.isSome(current)) {
+        yield* verify(current.value);
+        return yield* effect;
+    }
+    return yield* Effect.acquireUseRelease(WatchLease.acquire({ intervalSeconds: 300 }), (lease) => Effect.gen(function* () {
+        if (lease._tag === "Taken") {
+            return yield* new WriterGuardError({
+                reason: "taken",
+                message: "Another JCF writer holds the machine guard"
+            });
+        }
+        if (lease._tag === "Unavailable") {
+            return yield* new WriterGuardError({ reason: "unavailable", message: lease.reason });
+        }
+        return yield* withExistingWriterGuard(lease, effect);
+    }), (lease) => lease._tag === "Held" ? WatchLease.releaseGuard(lease) : Effect.void);
+});
+/**
+ * Serialize one provider mutation inside the live guard.
+ *
+ * Same-fiber nesting reuses the permit. A fork gets a different fiber id and must wait for the
+ * shared semaphore; after the owning guard releases, the live-lease check fails closed.
+ */
+export const mutate = (effect) => Effect.gen(function* () {
+    const ownerFiber = yield* Effect.fiberId;
+    const mutation = yield* Effect.serviceOption(MutationScope);
+    const writer = yield* Effect.serviceOption(WriterScope);
+    if (Option.isSome(mutation) && mutation.value.ownerFiber === ownerFiber) {
+        if (Option.isNone(writer)) {
+            return yield* new WriterGuardError({ reason: "missing", message: "Writer authority is missing" });
+        }
+        yield* verifyStanding(writer.value);
+        return yield* effect;
+    }
+    if (Option.isNone(writer))
+        return yield* withWriterGuard(mutate(effect));
+    const fiber = yield* writer.value.admission.withPermit(verify(writer.value).pipe(Effect.andThen(FiberSet.run(writer.value.fibers, writer.value.mutations.withPermit(Effect.gen(function* () {
+        yield* verifyStanding(writer.value);
+        const mutationFiber = yield* Effect.fiberId;
+        return yield* effect.pipe(Effect.provideService(MutationScope, { ownerFiber: mutationFiber }));
+    }))))));
+    return yield* Fiber.join(fiber);
+});
+//# sourceMappingURL=writerGuard.js.map

package/dist/src/cli/writerGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writerGuard.js","sourceRoot":"","sources":["../../../src/cli/writerGuard.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `@knpkv/jira-clockify` — the headless engine behind `jcf`.
+ *
+ * Namespace re-exports for clean imports.
+ *
+ * **What is here, and what is not**
+ *
+ * Everything a *second* surface needs to derive Proposed Worklogs and write a confirmed one: the
+ * pure agent-session core, the services, the live layer composition, the write path, and the
+ * calendar. Deliberately absent are the command definitions and the TUI — a consumer builds its own
+ * surface, and importing `effect/cli` or `@opentui/react` to reach a service would be a
+ * cost paid for nothing. The test seam lives at `@knpkv/jira-clockify/testing.js`, out of this
+ * barrel so nothing production imports it by accident.
+ *
+ * @example
+ * ```typescript
+ * import { AgentWrite, Layers, ReconcileService, Time } from "@knpkv/jira-clockify"
+ *
+ * const week = Time.isoWeekPeriod(new Date())
+ * const report = yield* (yield* ReconcileService.ReconcileService).proposeFromSessions(week)
+ * ```
+ *
+ * @module
+ */
+export * as AgentSessions from "./agent/sessions.js";
+export * as SourceConsumption from "./agent/sourceConsumption.js";
+export * as AgentWatch from "./agent/watch.js";
+export * as AgentWrite from "./cli/agentWrite.js";
+export * as Calendar from "./cli/calendar.js";
+export * as FetchTicket from "./cli/fetchTicket.js";
+export * as Layers from "./cli/layers.js";
+export * as WatchLease from "./cli/watchLease.js";
+export * as WriterGuard from "./cli/writerGuard.js";
+export * as AgentSessionReader from "./services/AgentSessionReader.js";
+export * as ClockifyAuth from "./services/ClockifyAuth.js";
+export * as ConfigService from "./services/ConfigService.js";
+export * as HomeDirectory from "./services/HomeDirectory.js";
+export * as IssueFacts from "./services/IssueFacts.js";
+export * as ReconcileService from "./services/ReconcileService.js";
+export * as SavedEntries from "./services/SavedEntries.js";
+export * as SessionAttributor from "./services/SessionAttributor.js";
+export * as StateWriter from "./services/StateWriter.js";
+export * as TicketService from "./services/TicketService.js";
+export * as TimerService from "./services/TimerService.js";
+export * as Time from "./utils/time.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,aAAa,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,iBAAiB,MAAM,8BAA8B,CAAA;AACjE,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,UAAU,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,OAAO,KAAK,WAAW,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,UAAU,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,WAAW,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,kBAAkB,MAAM,kCAAkC,CAAA;AACtE,OAAO,KAAK,YAAY,MAAM,4BAA4B,CAAA;AAC1D,OAAO,KAAK,aAAa,MAAM,6BAA6B,CAAA;AAC5D,OAAO,KAAK,aAAa,MAAM,6BAA6B,CAAA;AAC5D,OAAO,KAAK,UAAU,MAAM,0BAA0B,CAAA;AACtD,OAAO,KAAK,gBAAgB,MAAM,gCAAgC,CAAA;AAClE,OAAO,KAAK,YAAY,MAAM,4BAA4B,CAAA;AAC1D,OAAO,KAAK,iBAAiB,MAAM,iCAAiC,CAAA;AACpE,OAAO,KAAK,WAAW,MAAM,2BAA2B,CAAA;AACxD,OAAO,KAAK,aAAa,MAAM,6BAA6B,CAAA;AAC5D,OAAO,KAAK,YAAY,MAAM,4BAA4B,CAAA;AAC1D,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,46 @@
+/**
+ * `@knpkv/jira-clockify` — the headless engine behind `jcf`.
+ *
+ * Namespace re-exports for clean imports.
+ *
+ * **What is here, and what is not**
+ *
+ * Everything a *second* surface needs to derive Proposed Worklogs and write a confirmed one: the
+ * pure agent-session core, the services, the live layer composition, the write path, and the
+ * calendar. Deliberately absent are the command definitions and the TUI — a consumer builds its own
+ * surface, and importing `effect/cli` or `@opentui/react` to reach a service would be a
+ * cost paid for nothing. The test seam lives at `@knpkv/jira-clockify/testing.js`, out of this
+ * barrel so nothing production imports it by accident.
+ *
+ * @example
+ * ```typescript
+ * import { AgentWrite, Layers, ReconcileService, Time } from "@knpkv/jira-clockify"
+ *
+ * const week = Time.isoWeekPeriod(new Date())
+ * const report = yield* (yield* ReconcileService.ReconcileService).proposeFromSessions(week)
+ * ```
+ *
+ * @module
+ */
+export * as AgentSessions from "./agent/sessions.js";
+export * as SourceConsumption from "./agent/sourceConsumption.js";
+export * as AgentWatch from "./agent/watch.js";
+export * as AgentWrite from "./cli/agentWrite.js";
+export * as Calendar from "./cli/calendar.js";
+export * as FetchTicket from "./cli/fetchTicket.js";
+export * as Layers from "./cli/layers.js";
+export * as WatchLease from "./cli/watchLease.js";
+export * as WriterGuard from "./cli/writerGuard.js";
+export * as AgentSessionReader from "./services/AgentSessionReader.js";
+export * as ClockifyAuth from "./services/ClockifyAuth.js";
+export * as ConfigService from "./services/ConfigService.js";
+export * as HomeDirectory from "./services/HomeDirectory.js";
+export * as IssueFacts from "./services/IssueFacts.js";
+export * as ReconcileService from "./services/ReconcileService.js";
+export * as SavedEntries from "./services/SavedEntries.js";
+export * as SessionAttributor from "./services/SessionAttributor.js";
+export * as StateWriter from "./services/StateWriter.js";
+export * as TicketService from "./services/TicketService.js";
+export * as TimerService from "./services/TimerService.js";
+export * as Time from "./utils/time.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,aAAa,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,iBAAiB,MAAM,8BAA8B,CAAA;AACjE,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,UAAU,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAA;AAC7C,OAAO,KAAK,WAAW,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,UAAU,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,WAAW,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,kBAAkB,MAAM,kCAAkC,CAAA;AACtE,OAAO,KAAK,YAAY,MAAM,4BAA4B,CAAA;AAC1D,OAAO,KAAK,aAAa,MAAM,6BAA6B,CAAA;AAC5D,OAAO,KAAK,aAAa,MAAM,6BAA6B,CAAA;AAC5D,OAAO,KAAK,UAAU,MAAM,0BAA0B,CAAA;AACtD,OAAO,KAAK,gBAAgB,MAAM,gCAAgC,CAAA;AAClE,OAAO,KAAK,YAAY,MAAM,4BAA4B,CAAA;AAC1D,OAAO,KAAK,iBAAiB,MAAM,iCAAiC,CAAA;AACpE,OAAO,KAAK,WAAW,MAAM,2BAA2B,CAAA;AACxD,OAAO,KAAK,aAAa,MAAM,6BAA6B,CAAA;AAC5D,OAAO,KAAK,YAAY,MAAM,4BAA4B,CAAA;AAC1D,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAA"}

package/dist/src/main.d.ts

@@ -0,0 +1,4 @@
+import { Effect } from "effect";
+declare const program: Effect.Effect<void, never, never>;
+export default program;
+//# sourceMappingURL=main.d.ts.map

package/dist/src/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.tsx"],"names":[],"mappings":"AAOA,OAAO,EAAY,MAAM,EAAE,MAAM,QAAQ,CAAA;AAYzC,QAAA,MAAM,OAAO,mCA4BS,CAAA;eAEP,OAAO"}

package/dist/src/services/AgentSessionReader.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Read local Claude Code and Codex Agent Sessions as reconciliation evidence.
+ *
+ * **Mental model**
+ *
+ * - **Read-only evidence**: transcripts are never written, moved, or modified. This service only
+ *   reports what a session touched, when, and where — see ADR-0006.
+ * - **Opt-in scope**: a session becomes evidence only when its working directory sits inside a
+ *   configured Session Root. Claude project names allow a pre-read filter; Codex date directories
+ *   do not, so Codex working directories are checked after local decoding. Out-of-scope text never
+ *   reaches ticket mining, a Coding Agent or a proposal.
+ * - **Tolerant decoding**: the transcript layout is an external contract that changes without
+ *   notice. Unrecognised and malformed lines are skipped; a session survives on the lines it can
+ *   decode rather than failing the whole run.
+ * - **Presence, not busy-ness**: only messages the *person* typed count as Session Activity. A
+ *   transcript is overwhelmingly the agent's own output — measured on one real day, 1641 events of
+ *   which 66 were human — so counting every event measures how long the agent was busy, which is
+ *   not the same as how long anyone was working.
+ *
+ * **Gotchas**
+ *
+ * - A `user` line is not necessarily a person. Tool results come back as `user` messages whose
+ *   content is `tool_result` blocks, and they outnumber real prompts roughly ten to one. Only text
+ *   content counts.
+ * - Assistant output, sidechain turns, and tool results still feed the candidate Issue Keys and the
+ *   digest: they say nothing about presence, but plenty about *what* the session was for.
+ * - The working directory and branch are taken from the session's last in-window line of any kind —
+ *   the state the credited work actually ran under.
+ *
+ * @module
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { type AttributableSession, type SessionActivity } from "../agent/sessions.js";
+import { ConfigService } from "./ConfigService.js";
+import { HomeDirectory } from "./HomeDirectory.js";
+import type { ReconcilePeriod } from "./ReconcileService.js";
+/** One Agent Session, reduced to the evidence attribution and partitioning need. */
+export interface AgentSessionRecord extends AttributableSession {
+    /** Session Activity inside the requested window, ascending. */
+    readonly activity: ReadonlyArray<SessionActivity>;
+    /** Bounded digest of the session's prompts, for a Coding Agent to read. */
+    readonly digest: string;
+    /**
+     * Where this stretch of the transcript ended, when something followed it under a different branch
+     * or directory. Presence after its final prompt stops here rather than running the full Idle Cap.
+     */
+    readonly boundedAtMs: number | null;
+}
+declare const AgentSessionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "AgentSessionError";
+} & Readonly<A>;
+export declare class AgentSessionError extends AgentSessionError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+export interface AgentSessionReaderContract {
+    /**
+     * Every in-scope Agent Session with activity inside the period. Codex files are decoded locally
+     * to check their working directories; only in-scope segments become evidence.
+     */
+    readonly read: (period: ReconcilePeriod) => Effect.Effect<ReadonlyArray<AgentSessionRecord>, AgentSessionError>;
+}
+declare const AgentSessionReader_base: Context.ServiceClass<AgentSessionReader, "jcf/AgentSessionReader", AgentSessionReaderContract>;
+export declare class AgentSessionReader extends AgentSessionReader_base {
+}
+/** What one transcript file contributes, before scope and window filtering. */
+interface DecodedTranscript {
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly gitBranch: string | null;
+    readonly activity: ReadonlyArray<SessionActivity>;
+    /** Where this segment gave way to the next, or null when nothing followed it. */
+    readonly boundedAtMs: number | null;
+    /** Prompt text in transcript order — mined for candidate keys and folded into the digest. */
+    readonly texts: ReadonlyArray<string>;
+}
+/**
+ * Decode one transcript into the evidence it holds, keeping only activity inside `[from, to)`.
+ *
+ * Returns one entry per *segment* — a stretch of the transcript that ran under one working
+ * directory and one branch. A session that switches branch mid-run is two pieces of work, and
+ * taking the last line's branch for all of it would credit the morning's prompts to the afternoon's
+ * ticket. Under `jcf watch` that is worse than a misattribution: the morning can already have been
+ * written under the first ticket before the switch, and would then be derived again under the
+ * second, putting the same wall clock on two tickets.
+ *
+ * Segments that resolve to the same Issue Key are unioned again downstream, so splitting costs
+ * nothing when a branch change does not change the work. What it does cost is the gap *across* a
+ * switch, which is no longer bridged — an under-count of at most one Idle Cap, which is the
+ * direction this design prefers to be wrong in.
+ *
+ * Pure and total: a malformed line, an unparseable timestamp, or a file of pure noise yields no
+ * segments rather than an error.
+ */
+export declare const decodeTranscript: (content: string, period: {
+    readonly fromMs: number;
+    readonly toMs: number;
+}) => ReadonlyArray<DecodedTranscript>;
+/**
+ * True when a project directory could hold a session inside one of the Session Roots.
+ *
+ * A *filter*, not a decision. The encoding is many-to-one — a root `/a/b-c` and an out-of-root
+ * `/a/b/c` both become `-a-b-c` — so a directory it admits may still turn out to be elsewhere, and
+ * the authoritative check on the decoded `cwd` runs afterwards regardless. What it cannot do is
+ * exclude one wrongly: separators encode character-by-character after a trailing root separator
+ * is removed, and Windows root spelling is folded. The decoded `cwd` still decides scope.
+ *
+ * So the guarantee is bounded, and worth stating exactly: a transcript whose project directory
+ * cannot encode from any Session Root is never opened, which in a working set of any size is nearly
+ * all of them. A transcript that collides with a root's encoding is opened and then discarded
+ * unread — the honest limit of deciding scope from a lossy directory name.
+ */
+export declare const mayHoldSessionRoot: (projectDir: string, roots: ReadonlyArray<string>) => boolean;
+export declare const layer: Layer.Layer<AgentSessionReader, never, ConfigService | FileSystem.FileSystem | HomeDirectory | Path.Path>;
+export {};
+//# sourceMappingURL=AgentSessionReader.d.ts.map

package/dist/src/services/AgentSessionReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSessionReader.d.ts","sourceRoot":"","sources":["../../../src/services/AgentSessionReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AAInC,OAAO,EACL,KAAK,mBAAmB,EAKxB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAM5D,oFAAoF;AACpF,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,CAAA;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CACpC;;;;AAED,qBAAa,iBAAkB,SAAQ,uBAAsC;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;CAAG;AAEL,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,kBAAkB,CAAC,EAAE,iBAAiB,CAAC,CAAA;CAChH;;AAED,qBAAa,kBAAmB,SAAQ,uBAEvC;CAAG;AA6HJ,+EAA+E;AAC/E,UAAU,iBAAiB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,CAAA;IACjD,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACtC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,YAClB,MAAM,UACP;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KACzD,aAAa,CAAC,iBAAiB,CAAkE,CAAA;AA8FpG;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,eAAgB,MAAM,SAAS,aAAa,CAAC,MAAM,CAAC,KAAG,OAQlF,CAAA;AAEJ,eAAO,MAAM,KAAK,2GA4IjB,CAAA"}