new files v0.2

.gitignore

@@ -41,3 +41,7 @@ data.json
 
 # Exclude macOS Finder (System Explorer) View States
 .DS_Store
+
+# no need
+Makefile
+

pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: set this to true or false

src/card.test.ts

@@ -0,0 +1,127 @@
+// *************************************************************************
+// * (C)opyright 2026         by Ruben Carlo Benante                       *
+// *                                                                       *
+// * This program is free software; you can redistribute it and/or modify  *
+// *  it under the terms of the GNU General Public License as published by *
+// *  the Free Software Foundation, either version 3 of the License, or    *
+// *  (at your option) any later version.                                  *
+// *                                                                       *
+// * This program is distributed in the hope that it will be useful,       *
+// *  but WITHOUT ANY WARRANTY; without even the implied warranty of       *
+// *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
+// *  GNU General Public License for more details.                         *
+// *                                                                       *
+// * You should have received a copy of the GNU General Public License     *
+// *  along with this program.  If not, see http://www.gnu.org/licenses/.  *
+// *                                                                       *
+// * Contact author at:                                                    *
+// *  Ruben Carlo Benante                                                  *
+// *  rcb@beco.cc                                                          *
+// *************************************************************************
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseQualcardBlocks, selectBlockToPush } from './card.ts';
+
+test('parseQualcardBlocks: splits front/back on the first blank line', () => {
+	const md = [
+		'# Note title',
+		'',
+		'```qualcard',
+		'When is judicial review available?',
+		'',
+		'Only on a concrete case or controversy',
+		'brought by a party with standing.',
+		'```',
+		'',
+		'more prose that is never sent',
+	].join('\n');
+	const blocks = parseQualcardBlocks(md);
+	assert.equal(blocks.length, 1);
+	assert.equal(blocks[0].front, 'When is judicial review available?');
+	assert.equal(
+		blocks[0].back,
+		'Only on a concrete case or controversy\nbrought by a party with standing.',
+	);
+	assert.equal(blocks[0].hasAnswer, true);
+});
+
+test('parseQualcardBlocks: multi-line front collapses to a single-line title', () => {
+	const md = ['```qualcard', 'A very', 'long prompt', '', 'the answer', '```'].join(
+		'\n',
+	);
+	const blocks = parseQualcardBlocks(md);
+	assert.equal(blocks.length, 1);
+	assert.equal(blocks[0].front, 'A very long prompt');
+	assert.equal(blocks[0].back, 'the answer');
+});
+
+test('parseQualcardBlocks: several blocks become several cards', () => {
+	const md = [
+		'```qualcard',
+		'Front A',
+		'',
+		'Back A',
+		'```',
+		'',
+		'```qualcard',
+		'Front B',
+		'',
+		'Back B',
+		'```',
+	].join('\n');
+	const blocks = parseQualcardBlocks(md);
+	assert.equal(blocks.length, 2);
+	assert.equal(blocks[0].front, 'Front A');
+	assert.equal(blocks[1].front, 'Front B');
+	assert.equal(blocks[0].startLine, 0);
+	assert.equal(blocks[0].endLine, 4);
+	assert.equal(blocks[1].startLine, 6);
+	assert.equal(blocks[1].endLine, 10);
+});
+
+test('parseQualcardBlocks: a block with no blank line has no answer', () => {
+	const md = ['```qualcard', 'Just a prompt, no answer', '```'].join('\n');
+	const blocks = parseQualcardBlocks(md);
+	assert.equal(blocks.length, 1);
+	assert.equal(blocks[0].front, 'Just a prompt, no answer');
+	assert.equal(blocks[0].back, '');
+	assert.equal(blocks[0].hasAnswer, false);
+});
+
+test('parseQualcardBlocks: an unclosed fence is ignored', () => {
+	const md = ['```qualcard', 'dangling front', '', 'dangling back'].join('\n');
+	assert.equal(parseQualcardBlocks(md).length, 0);
+});
+
+test('selectBlockToPush: none / single / cursor / ambiguous', () => {
+	const md = [
+		'```qualcard',
+		'Front A',
+		'',
+		'Back A',
+		'```',
+		'',
+		'```qualcard',
+		'Front B',
+		'',
+		'Back B',
+		'```',
+	].join('\n');
+	const two = parseQualcardBlocks(md);
+
+	assert.equal(selectBlockToPush([], 0).reason, 'none');
+
+	const single = parseQualcardBlocks(['```qualcard', 'F', '', 'B', '```'].join('\n'));
+	const s = selectBlockToPush(single, 99);
+	assert.equal(s.reason, 'single');
+	assert.equal(s.block?.front, 'F');
+
+	const inB = selectBlockToPush(two, 7);
+	assert.equal(inB.reason, 'cursor');
+	assert.equal(inB.block?.front, 'Front B');
+
+	const outside = selectBlockToPush(two, 5);
+	assert.equal(outside.reason, 'ambiguous');
+	assert.equal(outside.block, null);
+});

src/card.ts

@@ -0,0 +1,137 @@
+// *************************************************************************
+// * (C)opyright 2026         by Ruben Carlo Benante                       *
+// *                                                                       *
+// * This program is free software; you can redistribute it and/or modify  *
+// *  it under the terms of the GNU General Public License as published by *
+// *  the Free Software Foundation, either version 3 of the License, or    *
+// *  (at your option) any later version.                                  *
+// *                                                                       *
+// * This program is distributed in the hope that it will be useful,       *
+// *  but WITHOUT ANY WARRANTY; without even the implied warranty of       *
+// *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
+// *  GNU General Public License for more details.                         *
+// *                                                                       *
+// * You should have received a copy of the GNU General Public License     *
+// *  along with this program.  If not, see http://www.gnu.org/licenses/.  *
+// *                                                                       *
+// * Contact author at:                                                    *
+// *  Ruben Carlo Benante                                                  *
+// *  rcb@beco.cc                                                          *
+// *************************************************************************
+
+// Pure block-parsing logic for ob2qualkard. No Obsidian imports, so it is
+// unit-testable in isolation. A card lives only inside a ```qualcard fenced
+// block; the first blank line splits the front (prompt -> Kanboard task title)
+// from the back (answer -> task description).
+
+export interface CardBlock {
+	// The prompt: first paragraph of the block, collapsed to a single line.
+	front: string;
+	// The answer: everything after the first blank line, trimmed.
+	back: string;
+	// True when a blank-line divider exists and the text after it is non-empty.
+	hasAnswer: boolean;
+	// 0-based line indices of the opening and closing fence lines.
+	startLine: number;
+	endLine: number;
+}
+
+// Opening fence: up to 3 spaces, 3+ backticks, the info string "qualcard".
+// Case-insensitive so ```Qualcard also works; documented as lowercase.
+const OPEN_RE = /^ {0,3}(`{3,})qualcard\s*$/i;
+
+// Extract every ```qualcard block from a note's Markdown text.
+export function parseQualcardBlocks(markdown: string): CardBlock[] {
+	const lines = markdown.split(/\r?\n/);
+	const blocks: CardBlock[] = [];
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i];
+		if (line === undefined) break;
+		const open = line.match(OPEN_RE);
+		if (!open) {
+			i++;
+			continue;
+		}
+		const fenceLen = open[1]?.length ?? 3;
+		// Closing fence: backticks only, at least as many as the opener.
+		const closeRe = new RegExp('^ {0,3}`{' + fenceLen + ',}\\s*$');
+		const content: string[] = [];
+		let j = i + 1;
+		let closed = false;
+		while (j < lines.length) {
+			const cur = lines[j];
+			if (cur === undefined) break;
+			if (closeRe.test(cur)) {
+				closed = true;
+				break;
+			}
+			content.push(cur);
+			j++;
+		}
+		if (closed) {
+			blocks.push(buildBlock(content, i, j));
+			i = j + 1;
+		} else {
+			// Unclosed fence: not a valid block; resume after the opener line.
+			i++;
+		}
+	}
+	return blocks;
+}
+
+function buildBlock(
+	content: string[],
+	startLine: number,
+	endLine: number,
+): CardBlock {
+	// Skip leading blank lines, then find the first blank line: the divider.
+	let start = 0;
+	while (start < content.length && content[start]?.trim() === '') start++;
+	let divider = -1;
+	for (let k = start; k < content.length; k++) {
+		if (content[k]?.trim() === '') {
+			divider = k;
+			break;
+		}
+	}
+	const frontLines = content.slice(
+		start,
+		divider === -1 ? content.length : divider,
+	);
+	const front = collapse(frontLines.join(' '));
+	const back = divider === -1 ? '' : content.slice(divider + 1).join('\n').trim();
+	return { front, back, hasAnswer: back.length > 0, startLine, endLine };
+}
+
+// Join wrapped lines into a single-line title, squeezing runs of whitespace.
+function collapse(text: string): string {
+	return text.replace(/\s+/g, ' ').trim();
+}
+
+export type SelectReason = 'none' | 'single' | 'cursor' | 'ambiguous';
+
+export interface Selection {
+	block: CardBlock | null;
+	reason: SelectReason;
+}
+
+// Pick which block the "push this note" command acts on:
+//   0 blocks  -> none
+//   1 block   -> that block (cursor position ignored)
+//   >1 blocks -> the block containing the cursor, else ambiguous (push nothing).
+export function selectBlockToPush(
+	blocks: CardBlock[],
+	cursorLine: number,
+): Selection {
+	if (blocks.length === 0) return { block: null, reason: 'none' };
+	if (blocks.length === 1) {
+		return { block: blocks[0] ?? null, reason: 'single' };
+	}
+	const hit = blocks.find(
+		(b) => cursorLine >= b.startLine && cursorLine <= b.endLine,
+	);
+	return hit
+		? { block: hit, reason: 'cursor' }
+		: { block: null, reason: 'ambiguous' };
+}

src/kanboard.ts

@@ -0,0 +1,86 @@
+// *************************************************************************
+// * (C)opyright 2026         by Ruben Carlo Benante                       *
+// *                                                                       *
+// * This program is free software; you can redistribute it and/or modify  *
+// *  it under the terms of the GNU General Public License as published by *
+// *  the Free Software Foundation, either version 3 of the License, or    *
+// *  (at your option) any later version.                                  *
+// *                                                                       *
+// * This program is distributed in the hope that it will be useful,       *
+// *  but WITHOUT ANY WARRANTY; without even the implied warranty of       *
+// *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
+// *  GNU General Public License for more details.                         *
+// *                                                                       *
+// * You should have received a copy of the GNU General Public License     *
+// *  along with this program.  If not, see http://www.gnu.org/licenses/.  *
+// *                                                                       *
+// * Contact author at:                                                    *
+// *  Ruben Carlo Benante                                                  *
+// *  rcb@beco.cc                                                          *
+// *************************************************************************
+
+// The only module that touches the network. Uses Obsidian's requestUrl (not
+// fetch) so the HTTP Basic auth header and cross-origin call work. The pure
+// request/response helpers live in rpc.ts and are unit-tested there.
+
+import { requestUrl } from 'obsidian';
+import { buildJsonRpcRequest, parseRpcResult, type RpcAuth } from './rpc';
+
+// Perform a JSON-RPC call and return its `result`, throwing a readable Error
+// on transport failures or Kanboard-reported errors.
+async function call(
+	auth: RpcAuth,
+	method: string,
+	params: Record<string, unknown>,
+): Promise<unknown> {
+	const req = buildJsonRpcRequest(auth, method, params);
+	const resp = await requestUrl({
+		url: req.url,
+		method: 'POST',
+		headers: req.headers,
+		body: req.body,
+		throw: false,
+	});
+	if (resp.status === 401) {
+		throw new Error('Authentication failed (check username and API token)');
+	}
+	let data: unknown;
+	try {
+		data = resp.json;
+	} catch {
+		throw new Error(`Unexpected response from Kanboard (HTTP ${resp.status})`);
+	}
+	return parseRpcResult(data);
+}
+
+// Resolve a board (Kanboard project) display name to its numeric id, or null.
+export async function getProjectIdByName(
+	auth: RpcAuth,
+	name: string,
+): Promise<number | null> {
+	const result = await call(auth, 'getProjectByName', { name });
+	if (!result || typeof result !== 'object') return null;
+	const id = (result as { id?: unknown }).id;
+	return id ? Number(id) : null;
+}
+
+// Create a Kanboard task (which QualKard adopts as a new "new" card). Returns
+// the new task id. project_id + title are the only required fields; QualKard's
+// server-side hook fills in the spaced-repetition state on creation.
+export async function createTask(
+	auth: RpcAuth,
+	projectId: number,
+	title: string,
+	description: string,
+): Promise<number> {
+	const result = await call(auth, 'createTask', {
+		title,
+		project_id: projectId,
+		description,
+	});
+	// createTask returns the new task id, or false on a validation failure.
+	if (!result || typeof result === 'boolean') {
+		throw new Error('Kanboard rejected the task (no id returned)');
+	}
+	return Number(result);
+}

src/rpc.test.ts

@@ -0,0 +1,54 @@
+// *************************************************************************
+// * (C)opyright 2026         by Ruben Carlo Benante                       *
+// *                                                                       *
+// * This program is free software; you can redistribute it and/or modify  *
+// *  it under the terms of the GNU General Public License as published by *
+// *  the Free Software Foundation, either version 3 of the License, or    *
+// *  (at your option) any later version.                                  *
+// *                                                                       *
+// * This program is distributed in the hope that it will be useful,       *
+// *  but WITHOUT ANY WARRANTY; without even the implied warranty of       *
+// *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
+// *  GNU General Public License for more details.                         *
+// *                                                                       *
+// * You should have received a copy of the GNU General Public License     *
+// *  along with this program.  If not, see http://www.gnu.org/licenses/.  *
+// *                                                                       *
+// * Contact author at:                                                    *
+// *  Ruben Carlo Benante                                                  *
+// *  rcb@beco.cc                                                          *
+// *************************************************************************
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildJsonRpcRequest, parseRpcResult } from './rpc.ts';
+
+test('buildJsonRpcRequest: endpoint, basic auth, and json-rpc body', () => {
+	const req = buildJsonRpcRequest(
+		{ baseUrl: 'https://organon.beco.cc', username: 'drbeco', apiToken: 'tok' },
+		'createTask',
+		{ title: 'T', project_id: 7, description: 'D' },
+	);
+	assert.equal(req.url, 'https://organon.beco.cc/jsonrpc.php');
+	assert.equal(req.headers['Content-Type'], 'application/json');
+	assert.equal(req.headers.Authorization, 'Basic ' + btoa('drbeco:tok'));
+	const body = JSON.parse(req.body);
+	assert.equal(body.jsonrpc, '2.0');
+	assert.equal(body.method, 'createTask');
+	assert.deepEqual(body.params, { title: 'T', project_id: 7, description: 'D' });
+});
+
+test('buildJsonRpcRequest: strips trailing slashes from the base URL', () => {
+	const req = buildJsonRpcRequest(
+		{ baseUrl: 'https://x.example///', username: 'u', apiToken: 't' },
+		'getMe',
+		{},
+	);
+	assert.equal(req.url, 'https://x.example/jsonrpc.php');
+});
+
+test('parseRpcResult: returns result, or throws error.message', () => {
+	assert.equal(parseRpcResult({ result: 42 }), 42);
+	assert.equal(parseRpcResult({ result: false }), false);
+	assert.throws(() => parseRpcResult({ error: { message: 'boom' } }), /boom/);
+});

src/rpc.ts

@@ -0,0 +1,68 @@
+// *************************************************************************
+// * (C)opyright 2026         by Ruben Carlo Benante                       *
+// *                                                                       *
+// * This program is free software; you can redistribute it and/or modify  *
+// *  it under the terms of the GNU General Public License as published by *
+// *  the Free Software Foundation, either version 3 of the License, or    *
+// *  (at your option) any later version.                                  *
+// *                                                                       *
+// * This program is distributed in the hope that it will be useful,       *
+// *  but WITHOUT ANY WARRANTY; without even the implied warranty of       *
+// *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        *
+// *  GNU General Public License for more details.                         *
+// *                                                                       *
+// * You should have received a copy of the GNU General Public License     *
+// *  along with this program.  If not, see http://www.gnu.org/licenses/.  *
+// *                                                                       *
+// * Contact author at:                                                    *
+// *  Ruben Carlo Benante                                                  *
+// *  rcb@beco.cc                                                          *
+// *************************************************************************
+
+// Pure Kanboard JSON-RPC helpers. No Obsidian imports, so both the request
+// builder and the response parser are unit-testable without the network.
+
+export interface RpcAuth {
+	baseUrl: string;
+	username: string;
+	apiToken: string;
+}
+
+export interface JsonRpcRequest {
+	url: string;
+	headers: Record<string, string>;
+	body: string;
+}
+
+// Build the authenticated JSON-RPC request for a Kanboard method. Kanboard
+// authenticates with HTTP Basic "user:token"; the endpoint is /jsonrpc.php.
+export function buildJsonRpcRequest(
+	auth: RpcAuth,
+	method: string,
+	params: Record<string, unknown>,
+): JsonRpcRequest {
+	const base = auth.baseUrl.replace(/\/+$/, '');
+	const token = toBase64(`${auth.username}:${auth.apiToken}`);
+	return {
+		url: `${base}/jsonrpc.php`,
+		headers: {
+			'Content-Type': 'application/json',
+			Authorization: `Basic ${token}`,
+		},
+		body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+	};
+}
+
+// btoa exists both in Obsidian (browser runtime) and in Node's test runner.
+function toBase64(s: string): string {
+	return btoa(s);
+}
+
+// Return the JSON-RPC `result`, or throw the `error.message` as an Error.
+export function parseRpcResult(data: unknown): unknown {
+	const d = data as { result?: unknown; error?: { message?: string } } | null;
+	if (d && d.error) {
+		throw new Error(d.error.message ?? 'Kanboard RPC error');
+	}
+	return d ? d.result : undefined;
+}