@iiiokojiadbi/shift 0.1.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/core/flows.ts CHANGED
@@ -44,6 +44,7 @@ import {
44
44
  waitContext,
45
45
  } from './texts/prompts'
46
46
  import { CONTINUING, NOT_MADE, renderTasks, type TaskView, UNSETTLED, WAITING } from './texts/rows'
47
+ import { numberTracks } from './track'
47
48
  import type { ArchiveInput, HandedBack, OpenInput, PendingShift, SessionFile, Settled, ShiftInput, Stuck, TaskFiles, Work } from './types'
48
49
 
49
50
  // The flows that do not depend on the harness: an adapter hands them the loaded project and what only it knows.
@@ -147,6 +148,7 @@ export async function acceptShift(project: Project, call: ShiftCall): Promise<{
147
148
  if (letterProblem !== null) return { deny: letterProblem }
148
149
 
149
150
  if (settings.enabled) await refreshDocs(project)
151
+ await numberTracks(project)
150
152
  const work = await readRecords(project)
151
153
  if (work === null) return { deny: `No board: create ${BOARD} by the sections in ${GUIDE_TOOL} and call again.` }
152
154
  const previousDir = await previousShift(project)
@@ -213,7 +215,7 @@ export async function openTask(project: Project, input: OpenInput): Promise<{ de
213
215
  const task: TaskFiles = {
214
216
  name: input.name,
215
217
  task: renderTask(input),
216
- track: input.items.map(item => `${formatItem('open', item.name, item.note)}\n`).join(''),
218
+ track: input.items.map((item, n) => `${formatItem('open', n + 1, item.name, item.note)}\n`).join(''),
217
219
  notes: [],
218
220
  }
219
221
  const listPath = `${root}/${TASK_LIST}`
@@ -226,7 +228,7 @@ export async function openTask(project: Project, input: OpenInput): Promise<{ de
226
228
  await store.write(`${folder}/${NAMES.track}`, task.track ?? '')
227
229
  await store.write(listPath, list)
228
230
 
229
- return { result: OPENED(input.name, formatTaskLine(input.status, input.name, input.name, input.about)) }
231
+ return { result: OPENED(input.name, formatTaskLine(input.status, input.name, input.name, input.about), task.track ?? '') }
230
232
  }
231
233
 
232
234
  function renderTask(input: OpenInput): string {
@@ -458,7 +460,10 @@ export async function tasksView(project: Project): Promise<string> {
458
460
  status: task.status,
459
461
  name: task.name,
460
462
  about: task.about,
461
- items: task.status === 'in progress' ? open.map(item => ({ status: item.status, name: item.name })) : null,
463
+ items:
464
+ task.status === 'in progress'
465
+ ? open.map(item => ({ status: item.status, name: item.id === null ? item.name : `#${item.id} ${item.name}` }))
466
+ : null,
462
467
  closed: items.length - open.length,
463
468
  total: items.length,
464
469
  })
package/core/input.ts CHANGED
@@ -139,7 +139,7 @@ export function parseTrackInput(raw: Record<string, unknown>): TrackInput | stri
139
139
  const status = optional(raw, 'status')
140
140
  const note = optional(raw, 'note')
141
141
  if (Array.isArray(raw.items) && raw.items.length > 0) {
142
- if (optional(raw, 'item') !== null) return 'Pass item inside items, or leave items out.'
142
+ if (optional(raw, 'item') !== null || raw.id !== undefined) return 'Pass id and item inside items, or leave items out.'
143
143
  const items: ItemChange[] = []
144
144
  for (const [n, each] of raw.items.entries()) {
145
145
  const change = itemChange(typeof each === 'object' && each !== null ? (each as Record<string, unknown>) : {})
@@ -151,7 +151,7 @@ export function parseTrackInput(raw: Record<string, unknown>): TrackInput | stri
151
151
 
152
152
  return typeof own === 'string' ? own : { task, items, own }
153
153
  }
154
- if (optional(raw, 'item') === null) {
154
+ if (optional(raw, 'item') === null && raw.id === undefined) {
155
155
  const own = ownStatus(status ?? '', note)
156
156
 
157
157
  return typeof own === 'string' ? own : { task, items: [], own }
@@ -161,12 +161,14 @@ export function parseTrackInput(raw: Record<string, unknown>): TrackInput | stri
161
161
  return typeof change === 'string' ? change : { task, items: [change], own: null }
162
162
  }
163
163
 
164
- // One item's change: its words, a status of a track item, a one-line note.
164
+ // One item's change: its id, or the text of a new item; a status of a track item, a one-line note.
165
165
  function itemChange(raw: Record<string, unknown>): ItemChange | string {
166
- const item = text(raw, 'item')
166
+ const item = optional(raw, 'item')
167
+ const id = itemId(raw.id)
167
168
  const status = text(raw, 'status')
168
169
  const note = optional(raw, 'note')
169
- if (item === '') return "item is empty: words of the item's name."
170
+ if (raw.id !== undefined && id === null) return 'id is the number of a track item, as in its #<id>.'
171
+ if ((id === null) === (item === null)) return 'Pass id to change an item, or item to add a new one.'
170
172
  if (!isOneOf(STATUSES, status)) return `status for a track item is one of ${quote(STATUSES)}.`
171
173
  for (const [key, value] of [
172
174
  ['item', item],
@@ -176,7 +178,13 @@ function itemChange(raw: Record<string, unknown>): ItemChange | string {
176
178
  if (problem !== null) return problem
177
179
  }
178
180
 
179
- return { item, status, note, add: raw.add === true }
181
+ return id === null ? { item: item ?? '', status, note } : { id, status, note }
182
+ }
183
+
184
+ // A positive whole number, given as one or as a string, with or without its `#`.
185
+ function itemId(raw: unknown): number | null {
186
+ const id = typeof raw === 'string' ? Number(raw.replace(/^#/, '')) : raw
187
+ return typeof id === 'number' && Number.isInteger(id) && id > 0 ? id : null
180
188
  }
181
189
 
182
190
  // The task's own status in TASKS.md: a waiting or deferred one carries its reason.
package/core/markdown.ts CHANGED
@@ -140,20 +140,24 @@ export function findDate(text: string): string | null {
140
140
  return null
141
141
  }
142
142
 
143
- // Every `- ` line of a text as an item; a line without a `[status]` has an empty one.
143
+ // Every `- ` line of a text as an item; a line without a `[status]` has an empty one, a track item without `#<id>`
144
+ // a null id.
144
145
  export function itemsOf(text: string): Item[] {
145
146
  return text.split('\n').flatMap((raw, index) => {
146
147
  if (!raw.startsWith('- ')) return []
147
148
  const line = raw.trim()
148
149
  const match = /^- \[([^\]]+)\] *(.*)$/.exec(line)
149
150
  const rest = match?.[2] ?? line.slice(2).trim()
150
- const cut = rest.indexOf(' — ')
151
+ const id = /^#(\d+) +/.exec(rest)
152
+ const named = id === null ? rest : rest.slice(id[0].length)
153
+ const cut = named.indexOf(' — ')
151
154
 
152
155
  return [
153
156
  {
154
157
  status: match?.[1] ?? '',
155
- name: cut === -1 ? rest : rest.slice(0, cut),
156
- note: cut === -1 ? null : rest.slice(cut + 3),
158
+ id: id === null ? null : Number(id[1]),
159
+ name: cut === -1 ? named : named.slice(0, cut),
160
+ note: cut === -1 ? null : named.slice(cut + 3),
157
161
  rest,
158
162
  line,
159
163
  index,
@@ -162,8 +166,8 @@ export function itemsOf(text: string): Item[] {
162
166
  })
163
167
  }
164
168
 
165
- export function formatItem(status: string, name: string, note: string | null): string {
166
- return `- [${status}] ${name}${note === null ? '' : ` — ${note}`}`
169
+ export function formatItem(status: string, id: number, name: string, note: string | null): string {
170
+ return `- [${status}] #${id} ${name}${note === null ? '' : ` — ${note}`}`
167
171
  }
168
172
 
169
173
  export function formatK(n: number): string {
@@ -112,8 +112,8 @@ Each fact lives in one place. Your records live in the project directory, not in
112
112
 
113
113
  const TASK_RULES = `A task is one line of work, split by meaning: a feature, an adapter, a migration. Each lives in \`${TASKS}/<name>/\`, \`<name>\` in ${NAME_RULE}:
114
114
  - \`task.md\` — what the task is: a \`# <title>\` line, then sections ${TASK_SECTIONS.map(s => `"${s}"`).join(', ')}, all required ("none" if empty). Update it as the task changes. Decisions and dead ends that matter only inside this task go here;
115
- - \`track.md\` — the task's tracker: one line per item, \`- [status] item — what matters\`, status: ${STATUSES.join(', ')}. Add items as you go and set their status with \`${TRACK_TOOL}\`, not by hand; closed items stay until the task is archived — the track is the task's history;
116
- - \`${NAMES.notes}/\` — notes, when a line is not enough: research, a decision worked out, evidence. A markdown file with a frontmatter \`description\` and nothing else required, linked from its item in \`track.md\` — \`- [open] item — see [what it holds](${NAMES.notes}/<file>.md)\` — or from \`task.md\` when it is about the whole task. After a shift a task in progress shows its notes as a list with their descriptions; open one when its item comes up. Most items need none.
115
+ - \`track.md\` — the task's tracker: one line per item, \`- [status] #<id> item — what matters\`, status: ${STATUSES.join(', ')}. Add items as you go and set their status with \`${TRACK_TOOL}\`, not by hand: it gives a new item its id and finds an item by it; closed items stay until the task is archived — the track is the task's history;
116
+ - \`${NAMES.notes}/\` — notes, when a line is not enough: research, a decision worked out, evidence. A markdown file with a frontmatter \`description\` and nothing else required, linked from its item in \`track.md\` — \`- [open] #3 item — see [what it holds](${NAMES.notes}/<file>.md)\` — or from \`task.md\` when it is about the whole task. After a shift a task in progress shows its notes as a list with their descriptions; open one when its item comes up. Most items need none.
117
117
 
118
118
  Open a task with \`${OPEN_TOOL}\`, which writes its folder, its files and its line valid at once. Every folder in \`${TASKS}/\` is in \`${TASK_LIST}\`, and every listed task has its folder. What is "in progress" there is what you are doing now — one task, several, or none.`
119
119
 
@@ -36,8 +36,8 @@ export const NOTE_KINDS = {
36
36
 
37
37
  export type NoteKind = keyof typeof NOTE_KINDS
38
38
 
39
- export const OPENED = (name: string, line: string) =>
40
- `Opened ${TASKS}/${name}/ with task.md and track.md, and its line in ${TASK_LIST}:\n${line}\nIts decisions, dead ends and owner decisions say "none" until there are some; add items as you go with ${TRACK_TOOL}.`
39
+ export const OPENED = (name: string, line: string, track: string) =>
40
+ `Opened ${TASKS}/${name}/ with task.md and track.md, and its line in ${TASK_LIST}:\n${line}\n${track === '' ? '' : `Its items, each changed with ${TRACK_TOOL} by its id:\n${track}`}Its decisions, dead ends and owner decisions say "none" until there are some; add items as you go with ${TRACK_TOOL}.`
41
41
 
42
42
  export const ARCHIVED = (name: string) =>
43
43
  `Archived to ${ARCHIVE}/${name}/, its line is in ${INDEX}, and ${TASK_LIST} no longer lists it: links to it now point into the archive. Lift to the board any of its decisions that still bind beyond it.`
@@ -76,29 +76,28 @@ export const OPEN_SCHEMA = {
76
76
 
77
77
  export const ARCHIVE_DESCRIPTION = `Archive a finished or dropped task: moves ${TASKS}/<name>/ to ${ARCHIVE}/<name>/ and adds its line to ${INDEX}. It also takes the task out of ${TASK_LIST}.`
78
78
 
79
- export const TRACK_DESCRIPTION = `Set a status instead of editing the records by hand. With item: a track item of the task — item is words of its name (before " — "), enough to find one; a fragment that finds none or several is refused with the items listed. Without item: the task's own status in ${TASK_LIST}. status — for an item ${quote(STATUSES)}; for a task ${quote(FOCUS)}. note — replaces what follows " — ": what matters, or the reason a task is deferred or waits (required then). add: true adds item as a new item. Several items at once — when a stage closes one item and opens the next: items, a list of {item, status, note, add}, applied together or not at all; status beside items is then the task's own.`
79
+ export const TRACK_DESCRIPTION = `Set a status instead of editing the records by hand. With id: the track item with that id, the number in its "#<id>". With item: a new item with that text, given the next id. Without either: the task's own status in ${TASK_LIST}. status — for an item ${quote(STATUSES)}; for a task ${quote(FOCUS)}. note — replaces what follows " — ": what matters, or the reason a task is deferred or waits (required then). Several items at once — when a stage closes one item and opens the next: items, a list of {id or item, status, note}, applied together or not at all; status beside items is then the task's own.`
80
80
 
81
81
  export const TRACK_SCHEMA = {
82
82
  type: 'object',
83
83
  properties: {
84
84
  task: { type: 'string', description: `The task's folder name in ${TASKS}/.` },
85
- item: { type: 'string', description: "Words of the track item's name; leave out to set the task's own status." },
85
+ id: { type: 'integer', description: 'The track item to change: the number in its "#<id>".' },
86
+ item: { type: 'string', description: 'The text of a new track item; what matters goes in note.' },
86
87
  status: { type: 'string', enum: [...new Set([...STATUSES, ...FOCUS])] },
87
88
  note: { type: 'string', description: 'One line: replaces what follows " — ".' },
88
- add: { type: 'boolean', description: 'true: add item as a new item.' },
89
89
  items: {
90
90
  type: 'array',
91
- description:
92
- 'Several items in one call, in place of item: each found or added as item alone would be; one that fails writes nothing.',
91
+ description: 'Several items in one call, in place of id and item: each changed or added as alone; one that fails writes nothing.',
93
92
  items: {
94
93
  type: 'object',
95
94
  properties: {
95
+ id: { type: 'integer' },
96
96
  item: { type: 'string' },
97
97
  status: { type: 'string', enum: [...STATUSES] },
98
98
  note: { type: 'string' },
99
- add: { type: 'boolean' },
100
99
  },
101
- required: ['item', 'status'],
100
+ required: ['status'],
102
101
  },
103
102
  },
104
103
  },
@@ -207,7 +206,7 @@ export const TOOL_TEXTS: Record<string, ToolText> = {
207
206
  [TRACK_TOOL]: {
208
207
  label: 'Task status',
209
208
  description: TRACK_DESCRIPTION,
210
- brief: `set a track item's status or add an item, found by words of its name, several at once with items; without an item, the task's own status in \`${TASK_LIST}\`.`,
209
+ brief: `set a track item's status by its id or add an item, several at once with items; without either, the task's own status in \`${TASK_LIST}\`.`,
211
210
  schema: TRACK_SCHEMA,
212
211
  },
213
212
  [HISTORY_TOOL]: {
package/core/track.ts CHANGED
@@ -6,9 +6,9 @@ import type { Store } from './store'
6
6
  import { formatTaskLine, taskLine } from './tasks'
7
7
  import type { Item, ItemChange, TrackInput } from './types'
8
8
 
9
- // Statuses set by a tool instead of an edit by hand: a track item found by the words of its name, or a task's own
10
- // line in TASKS.md. Items carry no ids — the records stay clean, and the agent knows the words it wrote; a fragment
11
- // that finds no item or several is refused with the items listed, so the wrong one is never changed.
9
+ // Statuses set by a tool instead of an edit by hand: a track item found by its id, or a task's own line in TASKS.md.
10
+ // An id is the item's `#<n>`, given by the mod when the item is added and never reused in the track: a call names an
11
+ // item in a few characters, not by the words of its name.
12
12
 
13
13
  export async function updateTrack(project: Project, input: TrackInput): Promise<{ deny: string } | { result: string }> {
14
14
  const { store, root } = project
@@ -45,7 +45,7 @@ async function setTaskStatus(
45
45
  return { result: `${TASK_LIST}: ${lines[at]}` }
46
46
  }
47
47
 
48
- // Every change applied to the track in order, then written once: one that finds no item or several writes nothing.
48
+ // Every change applied to the track in order, then written once: one that finds no item writes nothing.
49
49
  async function setItems(
50
50
  store: Store,
51
51
  root: string,
@@ -53,8 +53,9 @@ async function setItems(
53
53
  changes: readonly ItemChange[],
54
54
  ): Promise<{ deny: string } | { result: string }> {
55
55
  const path = taskFile(`${root}/${DIR}`, task, 'track')
56
- let text = await store.read(path)
57
- if (text === null) return { deny: `No ${TASKS}/${task}/track.md: the task is not open.` }
56
+ const read = await store.read(path)
57
+ if (read === null) return { deny: `No ${TASKS}/${task}/track.md: the task is not open.` }
58
+ let text = numberItems(read)
58
59
  const lines: string[] = []
59
60
  for (const [n, change] of changes.entries()) {
60
61
  const applied = applyItem(text, task, change)
@@ -72,29 +73,57 @@ async function setItems(
72
73
  function applyItem(text: string, task: string, change: ItemChange): { deny: string } | { text: string; line: string } {
73
74
  const lines = text.split('\n')
74
75
  const items = itemsOf(text).filter(item => item.status !== '')
75
- const listed = (found: readonly Item[]) => found.map((each, n) => `${n + 1}. ${each.line}`).join('\n')
76
- const wanted = change.item.toLowerCase()
77
76
 
78
- if (change.add) {
79
- if (items.some(each => each.name.toLowerCase() === wanted)) return { deny: `"${change.item}" is already an item of ${task}.` }
80
- const line = formatItem(change.status, change.item, change.note)
77
+ if ('item' in change) {
78
+ const wanted = change.item.toLowerCase()
79
+ const same = items.find(each => each.name.toLowerCase() === wanted)
80
+ if (same !== undefined) return { deny: `"${change.item}" is already an item of ${task}: #${same.id}.` }
81
+ const line = formatItem(change.status, nextId(items), change.item, change.note)
81
82
  const body = text.trimEnd()
82
83
 
83
84
  return { text: `${body === '' ? '' : `${body}\n`}${line}\n`, line }
84
85
  }
85
86
 
86
- const exact = items.filter(each => each.name.toLowerCase() === wanted)
87
- const found = exact.length === 1 ? exact : items.filter(each => each.name.toLowerCase().includes(wanted))
88
- if (found.length > 1) {
89
- return { deny: `"${change.item}" is in ${found.length} items of ${task}:\n${listed(found)}\nCall again with words that find one.` }
87
+ const found = items.find(each => each.id === change.id)
88
+ if (found === undefined) {
89
+ return { deny: `No item #${change.id} in ${task}. Its items:\n${items.map(each => each.line).join('\n')}` }
90
90
  }
91
- const only = found[0]
92
- if (only === undefined) {
93
- return {
94
- deny: `No item of ${task} has "${change.item}" in its name. Its items:\n${listed(items)}\nCall again with words of one of them, or add: true for a new item.`,
91
+ lines[found.index] = formatItem(change.status, change.id, found.name, change.note ?? found.note)
92
+
93
+ return { text: lines.join('\n'), line: lines[found.index] ?? '' }
94
+ }
95
+
96
+ // Ids for the track items without one, or with one an earlier item took — added by hand, or written before items had
97
+ // ids — numbered on from the highest; the text as it was when every item has its own.
98
+ export function numberItems(text: string): string {
99
+ const items = itemsOf(text).filter(item => item.status !== '')
100
+ let next = nextId(items)
101
+ const lines = text.split('\n')
102
+ const seen = new Set<number>()
103
+ for (const item of items) {
104
+ if (item.id !== null && !seen.has(item.id)) {
105
+ seen.add(item.id)
106
+ continue
95
107
  }
108
+ lines[item.index] = formatItem(item.status, next++, item.name, item.note)
96
109
  }
97
- lines[only.index] = formatItem(change.status, only.name, change.note ?? only.note)
98
110
 
99
- return { text: lines.join('\n'), line: lines[only.index] ?? '' }
111
+ return lines.join('\n')
112
+ }
113
+
114
+ // Every open task's track numbered where it has items without ids: done at a shift, so the tracks it hands back
115
+ // carry an id on every item.
116
+ export async function numberTracks(project: Project): Promise<void> {
117
+ const { store, root } = project
118
+ for (const task of await store.list(`${root}/${TASKS}`, 'dir')) {
119
+ const path = taskFile(`${root}/${DIR}`, task, 'track')
120
+ const text = await store.read(path)
121
+ if (text === null) continue
122
+ const numbered = numberItems(text)
123
+ if (numbered !== text) await store.write(path, numbered)
124
+ }
125
+ }
126
+
127
+ function nextId(items: readonly Item[]): number {
128
+ return Math.max(0, ...items.map(item => item.id ?? 0)) + 1
100
129
  }
package/core/types.ts CHANGED
@@ -11,9 +11,9 @@ export type Gauge = { base: number | null; hinted: number | null; unassisted: bo
11
11
 
12
12
  export type ShiftInput = { letter: string; after: ShiftAfter; about: string }
13
13
 
14
- // What task_track asks for: an item of a task's track by words of its name, or the task's own line in TASKS.md.
15
- // One track item's change: found by words of its name, or added.
16
- export type ItemChange = { item: string; status: string; note: string | null; add: boolean }
14
+ // What task_track asks for: items of a task's track, or the task's own line in TASKS.md.
15
+ // One track item's change: an item found by its id, or a new item by its text.
16
+ export type ItemChange = ({ id: number } | { item: string }) & { status: string; note: string | null }
17
17
  // Track items changed together, all or none, and the task's own status in TASKS.md.
18
18
  export type TrackInput = { task: string; items: ItemChange[]; own: { status: string; note: string | null } | null }
19
19
 
@@ -33,7 +33,7 @@ export type OpenInput = {
33
33
  export type ArchiveInput = { name: string; outcome: (typeof OUTCOMES)[number]; about: string }
34
34
 
35
35
  // A `- [status] name — note` line of a block: `rest` is all after the status, `index` the line's place in the text.
36
- export type Item = { status: string; name: string; note: string | null; rest: string; line: string; index: number }
36
+ export type Item = { status: string; id: number | null; name: string; note: string | null; rest: string; line: string; index: number }
37
37
 
38
38
  // The board's tasks: status, folder name and the note after the dash.
39
39
  export type FocusTask = { status: string; name: string; line: string }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iiiokojiadbi/shift",
3
- "version": "0.1.0",
3
+ "version": "0.28.0",
4
4
  "description": "The agent decides by itself when to shift: it keeps a work board and task folders, writes a letter to itself, and continues from where it stopped.",
5
5
  "license": "MIT",
6
6
  "type": "module",